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.

Related MCP server: history-rag

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

Source formats

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

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:

MCP: shared history inside every Agent

The stdio server exposes six tools:

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

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