CLI History Hub

English | 简体中文

A local-first, read-only history layer for Codex, Claude Code, OpenCode, and installable third-party Agent connectors.

CLI History Hub indexes local Agent sessions into one independent SQLite database. It gives you one Web interface for browsing and searching work across Agents, plus one MCP server that lets each connected Agent retrieve earlier context produced by the others.

What it helps you accomplish

CLI coding Agents usually keep useful context in incompatible local stores. A decision made in Claude Code is not automatically available in Codex; an OpenCode session may be difficult to find by project; multiple Codex data directories make the problem larger. CLI History Hub provides a common read-only index without replacing or modifying those source stores.

Use it to:

• Resume work across Agents. Search a project once and read the relevant Codex, Claude Code, or OpenCode thread before continuing elsewhere.
• See one project timeline. Group sessions by canonical working directory even when different Agents represent the path differently.
• Search across accounts and installations. Register multiple source roots with distinct labels and search them together or independently.
• Separate conversation from technical records. Read user/assistant messages first, then expand reasoning, tool calls, tool results, patches, and system events only when needed.
• Give Agents shared historical context. Register the Hub's six MCP tools in each CLI so an Agent can retrieve recent context, search older work, and read selected threads.
• Integrate another local Agent. Install a Python connector package that emits normalized records; Hub Core, storage, Web, and MCP code remain unchanged.
• Keep personal state out of Git. Runtime databases, logs, source paths, and Agent configuration live in user data directories, separate from the public source checkout.

Feature tour

Use English or Simplified Chinese

The Web interface follows an explicit ?lang=en or ?lang=zh-CN parameter, then a saved browser preference, then the browser language. The language selector updates navigation, filters, dates, errors, session details, and accessibility labels without clearing the current search or selected session. Conversation content and project data remain in their original language.

Browse by Agent or session

The timeline combines every registered source while retaining Agent, source, model, project, main/subagent, and archive facets. Each thread keeps a visible source badge, so aggregation never hides provenance.

Group work by project folder

Folder mode answers “what happened in this repository?” rather than “which CLI did I use?”. A folder card shows the per-Agent session counts, main-session count, latest activity, and recorded token total.

Search across Agents

Search covers user and assistant messages by default. Tool and event records can be included explicitly from Search Settings. Results retain folder and Agent grouping, which makes it possible to compare related decisions without loading every transcript.

Read a complete thread without losing structure

Thread detail shows the normalized conversation, model and source metadata, parent/child relationships, an automatically generated summary, and a separately expandable technical section.

Built-in support

Capability	Codex	Claude Code	OpenCode	Third-party connector
Local history import	Built in	Built in	Built in	Connector-defined
Incremental synchronization	Yes	Yes	Live database generations	Connector-defined
Live append/update handling	Yes	Yes	Yes, including WAL state	Connector-defined
Main and subagent relationships	Yes	Yes	Yes	Optional capability
Archived sessions	Yes	Source-dependent	Yes	Optional capability
Model and token metadata	Yes	Yes	Yes	Optional capability
Folder grouping	Yes	Yes	Yes	When cwd is emitted
Web and MCP access	Yes	Yes	Yes	Automatic after registration

Source formats

Agent	Conventional source	Reader behavior
Claude Code	~/.claude/projects/**/*.jsonl	Byte-offset JSONL cursor with truncation/compaction rebuild
Codex	~/.codex/sessions/**/rollout-*.jsonl plus state_5.sqlite	State metadata plus byte-offset rollout cursor; direct rollout fallback
OpenCode	~/.local/share/opencode/opencode.db	Read-only SQLite snapshot of committed database and WAL generations

Source files and databases are never migration targets. Connectors read them and return normalized records; only the independent Hub database is writable.

How it works

flowchart LR
    C["Codex rollouts + state index"] --> CC["Codex connector"]
    A["Claude Code JSONL"] --> AC["Claude Code connector"]
    O["OpenCode SQLite + WAL"] --> OC["OpenCode connector"]
    P["Installed Agent package"] --> PC["Third-party connector"]
    CC --> N["Normalized threads, messages, cursors"]
    AC --> N
    OC --> N
    PC --> N
    N --> H["Independent Hub SQLite + FTS5"]
    H --> W["Loopback Web UI"]
    H --> M["stdio MCP server"]

The connector boundary is intentional:

1. A connector detects and reads one Agent-specific source root.
2. It emits stable ThreadRecord, MessageRecord, optional CursorRecord, and recoverable SyncIssue values.
3. Hub Core validates connector identity and content limits, canonicalizes project paths, redacts sensitive patterns, and commits records and cursors in one transaction.
4. FTS5 and literal fallback provide deterministic search.
5. The Web UI and MCP server query only the independent Hub database.

See Connector SDK for the extension contract.

Quick start

Requirements

• Python 3.10 or newer.
• SQLite with FTS5 support for indexed full-text search. If FTS5 is unavailable, deterministic literal fallback still works.
• At least one supported Agent history directory, unless you are using a third-party connector.

Python 3.11 and newer use the standard-library TOML parser. Python 3.10 installs the small tomli compatibility dependency.

Install from a checkout

git clone https://github.com/smallpinksquare/cli-history-hub.git
cd cli-history-hub
python -m venv .venv

Activate the environment and install:

# Linux / macOS
source .venv/bin/activate
python -m pip install .

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
python -m pip install .

The latest release also provides a platform-independent wheel on the Releases page.

First synchronization

cli-history-hub sync
cli-history-hub status
cli-history-hub serve

Open http://127.0.0.1:8767. On an empty Hub database, sync checks every registered connector's conventional source locations and registers the directories that exist. Missing Agents do not cause a failure.

The Web server runs a background incremental synchronization every 30 seconds by default. cli-history-hub sync remains useful for scripts, diagnostics, or a one-shot refresh without starting the website.

Installation choices

Isolated Windows user installation

The included installer creates a dedicated virtual environment and runtime directory instead of placing the database in the Git checkout:

powershell -ExecutionPolicy Bypass -File scripts\install_user.ps1

Default locations:

%LOCALAPPDATA%\CLIHistoryHub\.venv\Scripts\cli-history-hub.exe
%LOCALAPPDATA%\CLIHistoryHub\history-hub.db

Specify another Python executable or runtime root when needed:

powershell -ExecutionPolicy Bypass -File scripts\install_user.ps1 `
  -Python py `
  -RuntimeRoot C:\path\to\CLIHistoryHub

To adopt an older Hub database during installation:

powershell -ExecutionPolicy Bypass -File scripts\install_user.ps1 `
  -LegacyDatabase C:\path\to\old-history-hub.db

The old database is opened read-only and remains in place. The target must not already exist. See the installation and operations guide for the complete deployment, upgrade, validation, and removal workflow.

Upgrade an existing installation

From an updated checkout, run the installer again or reinstall the package in the selected virtual environment. Normal startup applies transactional schema migrations to the Hub-owned database. Before a versioned migration, the Hub creates a SQLite-consistent sibling backup named <database>.pre-v<target>.bak; existing backups are never overwritten.

Web UI usage

Start the server with an explicit database or port when required:

cli-history-hub --db /path/to/history-hub.db serve --host 127.0.0.1 --port 8767 --sync-interval 30

The main surfaces are:

1. Agent/session mode — filter by Agent, registered source, model, project, main session, subagent, or archived state.
2. Folder mode — group all sessions that share a canonical working directory, regardless of the producing Agent.
3. Cross-agent search — search conversation text, optionally including technical records.
4. Thread detail — inspect the summary, conversation, source metadata, parent/child relationships, and expandable technical records.
5. Health summary — verify indexed thread/message/folder totals plus missing items and recoverable connector errors.

The server binds to loopback by default and serves no remote assets. Do not bind it to a public interface unless you place it behind an authenticated reverse proxy appropriate for sensitive conversation data.

Register additional sources and accounts

Each source has a display name, source root, and connector ID. Use separate names for multiple accounts or installations:

cli-history-hub add-source --name codex-personal --path /path/to/personal-codex-home --type codex
cli-history-hub add-source --name codex-work --path /path/to/work-codex-home --type codex
cli-history-hub add-source --name claude-secondary --path /path/to/claude-projects --type claude
cli-history-hub sync
cli-history-hub sources

Use --type auto when exactly one installed connector recognizes the directory:

cli-history-hub add-source --name another-agent --path /path/to/history --type auto

Registration never copies or rewrites the source. The source label remains available as a Web and MCP filter.

CLI reference

Global options must appear before the command:

cli-history-hub [--config FILE] [--db FILE] COMMAND

Command	Purpose
sync	Discover default sources on first run, then perform one incremental synchronization
serve	Start the loopback Web UI and periodic synchronization loop
mcp	Run the stdio MCP server; stdout is reserved for JSON-RPC
status	Print indexed totals, source health, and connector metadata
sources	List registered source labels and their public synchronization state
connectors	List registered connector IDs, capabilities, and indexed counts
add-source --name NAME --path PATH --type ID	Add or update a named source root
adopt-database --from-db FILE	Create a consistent copy of an older Hub database at the selected --db path
set-summary --project NAME --text TEXT	Store a durable Hub-only project summary; use --project-path for duplicate folder names

Examples:

cli-history-hub connectors
cli-history-hub --db /path/to/history-hub.db sync
cli-history-hub --db /path/to/history-hub.db status
cli-history-hub --db /new/path/history-hub.db adopt-database --from-db /old/path/history-hub.db

Configuration

Settings resolve in this order:

built-in defaults < TOML file < HISTORY_HUB_* environment variables < CLI options

Copy config.example.toml to the default configuration location or select it with --config / HISTORY_HUB_CONFIG:

[hub]
db_path = "history-hub.db"
log_path = "history-hub-server.log"
host = "127.0.0.1"
port = 8767
sync_interval = 30

Relative paths in a TOML file resolve from that file's directory. Supported environment variables are:

• HISTORY_HUB_CONFIG
• HISTORY_HUB_DB
• HISTORY_HUB_LOG
• HISTORY_HUB_HOST
• HISTORY_HUB_PORT
• HISTORY_HUB_SYNC_INTERVAL

Default runtime locations:

Platform	Configuration	Database	Log
Windows	%APPDATA%\CLIHistoryHub\config.toml	%LOCALAPPDATA%\CLIHistoryHub\history-hub.db	%LOCALAPPDATA%\CLIHistoryHub\history-hub-server.log
Linux	$XDG_CONFIG_HOME/cli-history-hub/config.toml	$XDG_DATA_HOME/cli-history-hub/history-hub.db	$XDG_STATE_HOME/cli-history-hub/history-hub-server.log
macOS	~/Library/Application Support/CLIHistoryHub/config.toml	same directory, history-hub.db	~/Library/Application Support/CLIHistoryHub/Logs/history-hub-server.log

MCP: shared history inside every Agent

The stdio server exposes six tools:

Tool	Intended use
history_get_recent_context	Load a project overview and a small number of recent primary threads
history_search	Search older cross-project history, optionally filtering by connector, source, model, or project
history_get_thread	Read a selected thread in summary, relevant, or full mode
history_list_connectors	Discover registered connector IDs, capabilities, and counts
history_get_project_summary	Read the durable Hub-only project overview
history_update_project_summary	Update the durable overview in the Hub without touching Agent source stores

Use one absolute executable path and one absolute Hub database path in all three clients. If cli-history-hub is reliably available in every client's PATH and the default database is intended, the shorter command = "cli-history-hub" form is sufficient.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.cli_history_hub]
command = "/absolute/path/to/cli-history-hub"
args = ["--db", "/absolute/path/to/history-hub.db", "mcp"]
enabled = true

The configuration follows the current Codex mcp_servers.<id> reference. Restart or open a new Codex session after changing the file.

Claude Code

The CLI command is less error-prone than editing ~/.claude.json manually:

claude mcp add --transport stdio --scope user cli_history_hub -- \
  /absolute/path/to/cli-history-hub --db /absolute/path/to/history-hub.db mcp
claude mcp get cli_history_hub

For a repository-shared .mcp.json, use the official command plus args structure and replace the paths with portable environment-variable expressions. Claude Code requires project-scoped servers to be approved before first use. See the Claude Code MCP documentation.

OpenCode V2

Define the local stdio server under mcp.servers in the OpenCode configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "cli_history_hub": {
        "type": "local",
        "command": [
          "/absolute/path/to/cli-history-hub",
          "--db",
          "/absolute/path/to/history-hub.db",
          "mcp"
        ]
      }
    }
  }
}

OpenCode V2 connects local servers unless disabled is true; it does not use an enabled field. See the OpenCode MCP server reference.

After configuring a client, restart it and ask it to list history_* tools. A healthy server reports six tools.

Install another Agent connector

Third-party connectors are Python packages installed into the same environment as CLI History Hub. They register one entry point:

[project.entry-points."cli_history_hub.connectors"]
myagent = "myagent_history.connector:MyAgentConnector"

After installation:

cli-history-hub connectors
cli-history-hub add-source --name myagent --path /path/to/myagent/history --type myagent
cli-history-hub sync

The Web UI, API, MCP filter schema, and source discovery list update from the connector registry. Install only trusted connector packages: they execute inside the Hub process and can read the source directory they are given.

The complete protocol, normalized record rules, capability flags, and test expectations are in Connector SDK.

Privacy and security boundaries

• Original Agent transcripts and databases are opened read-only by the built-in connectors.
• The Hub writes only its independent SQLite database, migration backups, and optional log.
• Common API keys, bearer credentials, email addresses, and user-home paths are redacted during ingestion and privacy migrations.
• Project paths are canonicalized for grouping and redacted for public output where appropriate.
• The Web server defaults to 127.0.0.1, uses a strict Content Security Policy, loads no remote assets, and sends no telemetry.
• Tool/event records are excluded from normal search unless explicitly enabled.
• Repository CI scans both the current tree and every reachable Git blob for private runtime files and common secret patterns.
• Redaction is defense in depth, not permission to publish a real Hub database or transcript.

Read Runtime and repository boundaries and Security policy before reporting an issue with source data.

Current limitations

• This is a local history index, not a hosted synchronization service. It does not synchronize data between machines by itself.
• Built-in connectors target the currently documented local stores; upstream Agent schema changes may require connector updates.
• OpenCode visibility follows committed SQLite/WAL state and may trail an in-progress write until the next synchronization.
• Path-based folder grouping requires a connector to provide a meaningful working directory.
• The Web UI has no built-in remote authentication because it is designed for loopback use.
• Ingestion redaction cannot recognize every possible secret format or sensitive sentence.

Troubleshooting

Symptom	Check
sync indexes zero threads	Run connectors, then sources; register the actual source root with add-source if it is nonstandard
One source reports errors	Run status; verify the source still exists and the installed connector matches its current schema
Web totals do not change	Run a manual sync, then reload; confirm the Web process uses the same --db path
Sessions from one folder do not group	Compare their recorded working directories; path aliases and symlinks may represent different canonical locations
MCP server is missing	Use an absolute executable path, verify the absolute database path, and restart the client
MCP connects with zero tools	Run the exact command manually; a stdio server should remain silent and wait for JSON-RPC input
Claude Code shows a failed server	Run claude mcp get cli_history_hub and inspect /mcp
An older Hub database must move	Use adopt-database; never copy a live SQLite file with a normal filesystem copy
A connector plugin is not listed	Confirm it is installed in the same Python environment and registered under cli_history_hub.connectors

The installation and operations guide contains a complete decision table for installation, synchronization, Web, MCP, migration, upgrade, and removal issues.

Development

python -B -m unittest discover -s tests -v
python -B scripts/check_public_tree.py
python -B scripts/check_public_history.py
node --check history_hub/static/app.js

Documentation screenshots are generated from deterministic synthetic sources. See Demo data and screenshots before replacing an image.

Every behavior change requires regression coverage with synthetic or manually sanitized fixtures. Commits follow Conventional Commits and keep one independently testable task per commit. See Contributing.

Project status and license

CLI History Hub is currently an alpha release. Review the changelog, latest release, and open issues before depending on an undocumented source schema.

MIT © 2026 smallpinksquare