The CLI History Hub server provides a read-only interface to indexed CLI agent history, enabling agents (such as Codex, Claude Code, OpenCode, and third-party connectors) to share and query each other's session history.
Retrieve recent context (history_get_recent_context): Get a project overview and recent primary conversation summaries across all or a specific agent, with configurable limits and optional subagent inclusion.
Search cross-agent history (history_search): Perform full-text search across all indexed sessions with optional filters like connector, source, model, and project. Can include technical records for deeper search, returning up to 100 results.
Read a specific thread (history_get_thread): Load a conversation thread by ID in summary, relevant, or full detail modes, with configurable character limits and optional tool/event records.
List connectors (history_list_connectors): Discover all registered history connectors, their capabilities, and indexed source/thread counts.
Get project summary (history_get_project_summary): Retrieve a durable, Hub-stored overview of a project without full transcripts, with optional path disambiguation.
Update project summary (history_update_project_summary): Modify the durable project overview stored in the Hub database, without altering source CLI session files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cli-history-hub search my Claude Code history for the last error"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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: Codex History Hub
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.
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.
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 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.
Thread detail shows the normalized conversation, model and source metadata, parent/child relationships, an automatically generated summary, and a separately expandable technical section.
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 |
Web and MCP access | Yes | Yes | Yes | Automatic after registration |
Agent | Conventional source | Reader behavior |
Claude Code |
| Byte-offset JSONL cursor with truncation/compaction rebuild |
Codex |
| State metadata plus byte-offset rollout cursor; direct rollout fallback |
OpenCode |
| 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.
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:
A connector detects and reads one Agent-specific source root.
It emits stable ThreadRecord, MessageRecord, optional CursorRecord, and recoverable SyncIssue values.
Hub Core validates connector identity and content limits, canonicalizes project paths, redacts sensitive patterns, and commits records and cursors in one transaction.
FTS5 and literal fallback provide deterministic search.
The Web UI and MCP server query only the independent Hub database.
See Connector SDK for the extension contract.
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.
git clone https://github.com/smallpinksquare/cli-history-hub.git
cd cli-history-hub
python -m venv .venvActivate 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.
cli-history-hub sync
cli-history-hub status
cli-history-hub serveOpen 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.
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.ps1Default locations:
%LOCALAPPDATA%\CLIHistoryHub\.venv\Scripts\cli-history-hub.exe
%LOCALAPPDATA%\CLIHistoryHub\history-hub.dbSpecify another Python executable or runtime root when needed:
powershell -ExecutionPolicy Bypass -File scripts\install_user.ps1 `
-Python py `
-RuntimeRoot C:\path\to\CLIHistoryHubTo adopt an older Hub database during installation:
powershell -ExecutionPolicy Bypass -File scripts\install_user.ps1 `
-LegacyDatabase C:\path\to\old-history-hub.dbThe 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.
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.
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 30The main surfaces are:
Agent/session mode — filter by Agent, registered source, model, project, main session, subagent, or archived state.
Folder mode — group all sessions that share a canonical working directory, regardless of the producing Agent.
Cross-agent search — search conversation text, optionally including technical records.
Thread detail — inspect the summary, conversation, source metadata, parent/child relationships, and expandable technical records.
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.
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 sourcesUse --type auto when exactly one installed connector recognizes the directory:
cli-history-hub add-source --name another-agent --path /path/to/history --type autoRegistration never copies or rewrites the source. The source label remains available as a Web and MCP filter.
Global options must appear before the command:
cli-history-hub [--config FILE] [--db FILE] COMMANDCommand | Purpose |
| Discover default sources on first run, then perform one incremental synchronization |
| Start the loopback Web UI and periodic synchronization loop |
| Run the stdio MCP server; stdout is reserved for JSON-RPC |
| Print indexed totals, source health, and connector metadata |
| List registered source labels and their public synchronization state |
| List registered connector IDs, capabilities, and indexed counts |
| Add or update a named source root |
| Create a consistent copy of an older Hub database at the selected |
| Store a durable Hub-only project summary; use |
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.dbSettings resolve in this order:
built-in defaults < TOML file < HISTORY_HUB_* environment variables < CLI optionsCopy 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 = 30Relative 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 |
|
|
|
Linux |
|
|
|
macOS |
| same directory, |
|
The stdio server exposes six tools:
Tool | Intended use |
| Load a project overview and a small number of recent primary threads |
| Search older cross-project history, optionally filtering by connector, source, model, or project |
| Read a selected thread in summary, relevant, or full mode |
| Discover registered connector IDs, capabilities, and counts |
| Read the durable Hub-only project overview |
| 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.
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 = trueThe configuration follows the current Codex mcp_servers.<id> reference. Restart or open a new Codex session after changing the file.
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_hubFor 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.
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.
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 syncThe 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.
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.
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.
Symptom | Check |
| Run |
One source reports errors | Run |
Web totals do not change | Run a manual |
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 |
An older Hub database must move | Use |
A connector plugin is not listed | Confirm it is installed in the same Python environment and registered under |
The installation and operations guide contains a complete decision table for installation, synchronization, Web, MCP, migration, upgrade, and removal issues.
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.jsDocumentation 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.
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
Get the durable overview of a project without loading conversation transcripts.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | ||
| project_path | No | Disambiguate projects that share the same folder name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It notes the 'durable' nature and the fact that it avoids loading transcripts, which hints at non-destructive, lightweight behavior. However, it does not explicitly confirm it is read-only or describe side effects/permissions, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is clear and free of filler. It communicates the core purpose and key differentiator efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should clarify what the 'overview' contains or how to specify the project. It does explain the benefit over transcript loading, but leaves out return value details and the nuanced role of both parameters, making it only moderately complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: 'project_path' has a description, but 'project' is undocumented. The tool description does not explain either parameter or their relationship, leaving the agent without guidance on how to disambiguate when both are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and clearly identifies the resource: 'durable overview of a project.' It also distinguishes from siblings by adding 'without loading conversation transcripts,' which separates it from tools like history_get_thread or history_get_recent_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the intended use case: when you need a quick overview and want to avoid loading full transcripts. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a project overview plus recent primary conversation summaries across registered agents. Subagents are excluded by default.
| Name | Required | Description | Default |
|---|---|---|---|
| cli | No | Optional connector ID. Omit to search every registered agent. | |
| limit | No | ||
| source | No | ||
| project | No | ||
| include_subagents | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the subagent exclusion default, which is useful, but doesn't mention read-only nature, pagination, or exact data scope beyond 'registered agents.' Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy, front-loaded with the action and result. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks detail on return shape, parameter semantics (limit, source, project), and how this relates to sibling tools. For a tool with 5 parameters and no output schema, this is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
What is the meaning of parameters with schema coverage only 20% and description lacking detail? The description adds context for include_subagents via the default note but ignores limit, source, and project entirely, failing to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a project overview plus recent primary conversation summaries across registered agents, and notes subagents are excluded by default. This distinguishes it from siblings like history_search and history_get_thread, though the term 'primary' is slightly ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance or naming of alternatives. The description implies use for getting recent context but doesn't clarify when to choose this over history_get_project_summary or history_get_thread.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a selected history thread after identifying it via recent context or search. Full mode should be used only when the user explicitly requests the full thread.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | relevant | |
| query | No | ||
| max_chars | No | ||
| thread_id | Yes | ||
| include_tools | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses a caution about 'full' mode requiring explicit user request, which is useful. However, it does not describe return behavior, side effects, or cost implications for other modes (summary/relevant).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, direct and front-loaded. Every word earns its place, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no output schema, and no annotations, the description is far from complete. It omits parameter semantics, return value expectations, and any mention of resource costs besides the 'full mode' caution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It only references 'full mode' (one enum value) but does not explain thread_id, query, max_chars, include_tools, or mode differences. This is insufficient for 5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'read' and the resource 'history thread', and introduces the prerequisite of identifying the thread via recent context or search. It does not explicitly name sibling tools, but the reference to 'recent context or search' strongly implies the context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a usage flow (identify thread first) and provides a specific constraint for 'full' mode, but does not explicitly state when to use this tool versus alternatives or provide exclusions. Sibling tools are not named, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List registered history connectors, their capabilities, and indexed source/thread counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. The verb 'List' and the explicit mention of returned data (capabilities and counts) transparently convey a read-only inventory operation. It does not suggest any side effects or hidden behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with a front-loaded verb and specific objects. There is no filler, redundancy, or ambiguity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description adequately covers its function and return content. It specifies what will be listed (connectors, capabilities, counts) and is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and the schema already documents this fully (100% coverage). With no parameters to explain, a baseline of 4 applies, and the description adds no unnecessary parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('registered history connectors') and elaborates on what is returned (capabilities and indexed source/thread counts). This clearly differentiates it from siblings like history_search and history_get_thread, which are retrieval operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining an inventory of connectors and their statistics, but it does not explicitly contrast with sibling tools or state when not to use it. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search older cross-project history across every registered agent. Call only when the user explicitly asks to search past history, names an older date/source/topic, or recent context is insufficient.
| Name | Required | Description | Default |
|---|---|---|---|
| cli | No | Optional connector ID. Omit to search every registered agent. | |
| limit | No | ||
| model | No | ||
| query | Yes | ||
| source | No | ||
| project | No | ||
| include_technical | No | Also search tool and event records (thinking, tool calls/results). Disabled by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It usefully reveals that the tool searches across every registered agent and targets older, cross-project history. However, it does not disclose return format, pagination, performance implications, or how results are aggregated beyond the schema's limited parameter notes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no filler. Every clause adds value: 'older', 'cross-project', 'every registered agent', and the specific usage triggers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good purpose and usage guidance, the tool has 7 parameters, no output schema, and no annotations. The description does not cover required parameter semantics, return value shape, or how the search behaves across connectors/projects, leaving significant gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29%, so the description must compensate for undocumented parameters. It does not explain the required 'query' parameter, nor the optional 'model', 'source', or 'project' parameters. The description only hints at 'source/topic' in the usage guidance, which is insufficient for the 7-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Search') and resource ('older cross-project history across every registered agent'). It distinguishes this from sibling tools by emphasizing 'older' and 'cross-project', which sets it apart from history_get_recent_context and history_get_thread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit trigger conditions: 'only when the user explicitly asks to search past history, names an older date/source/topic, or recent context is insufficient.' This strongly implies when not to use it and contrasts with recent-context tools, though it does not name the alternative sibling tools explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the confirmed durable project overview in the independent Hub only. Never writes to any source CLI session files.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| summary | Yes | ||
| project_path | No | Required when multiple folders share the project name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose a key side effect boundary (writes only to Hub, never to source CLI files). However, it omits other behavior an agent might need, such as whether the summary is fully overwritten, permission requirements, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and immediately clarifying the scope boundary. Every clause adds value with no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool, the core side effect and scope are covered. But ambiguity in 'confirmed durable' and missing parameter semantics mean the agent still lacks enough context to safely invoke it in all cases (e.g., when project_path is required).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only project_path is described). The description does not compensate by explaining the 'project' or 'summary' parameters or their expected formats, leaving the agent to guess what 'summary' should contain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and a specific resource ('confirmed durable project overview in the independent Hub'), with a clear scope boundary ('Hub only'). It distinguishes from the sibling read tool history_get_project_summary by action, though the phrase 'confirmed durable' is somewhat opaque.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the intended context (updating the durable overview in the Hub) and explicitly excludes source CLI session files ('Never writes to any source CLI session files'). It does not name alternative tools, but the usage context is reasonably clear for a targeted update tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0history_get_project_summaryhistory_get_recent_contexthistory_get_threadhistory_list_connectorshistory_searchhistory_update_project_summaryScored across 6 tools
Most tools have clearly distinct purposes, but history_get_recent_context and history_get_project_summary both return project overviews, which could cause confusion. The other tools (search, get_thread, list_connectors, update_summary) are unambiguous.
All tools use the history_ prefix with snake_case and mostly follow a verb_noun pattern (get_recent_context, get_thread, list_connectors, get_project_summary, update_project_summary). The exception is history_search, which uses a bare verb, but the overall style is consistent.
With six tools, the set is well-scoped for managing CLI history—covering retrieval, search, thread access, connector listing, and project summary management. This is an appropriate size, not too thin or overwhelming.
The tools cover the core workflows: recent context, historical search, thread retrieval, connector discovery, and project summary viewing/updating. No critical operations are missing for the stated purpose of a history hub.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
Agent-native launch platform and tool directory: search, alternatives, trending, launch via MCP.
