WheelDrop Logbook

The flight recorder for your AI coding agents. An MCP server that gives Claude Code, Codex, and Gemini CLI a shared, persistent memory.

Your AI coding agents have amnesia. Every session starts from scratch — no memory of what you built yesterday, what patterns you chose, or what mistakes were already solved. WheelDrop Logbook fixes this by indexing your agents' conversation history, memory files, and plans into a searchable MCP server that any agent can query.

Quick Start

Auto-detect installed agents and configure them all:

npx @wheeldrop/logbook --install

This detects which agents you have (Claude Code, Codex CLI, Gemini CLI), configures each one to use Logbook as an MCP server, and installs agent-specific skills where supported. The installer also copies a skill file to ~/.codex/skills/logbook/ so Codex auto-triggers conversation search when relevant.

Per-Agent Setup

Claude Code

Plugin install:

claude plugin marketplace add wheeldrop/logbook
claude plugin install logbook@logbook

MCP server only (no skill/context):

claude mcp add logbook --scope user -e -- npx @wheeldrop/logbook

Gemini CLI

Extension install:

gemini extensions install https://github.com/wheeldrop/logbook

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.logbook]
command = "npx"
args = ["@wheeldrop/logbook"]

Optionally, copy the bundled skill for auto-triggered search:

mkdir -p ~/.codex/skills/logbook
cp $(npm root -g)/@wheeldrop/logbook/skills/logbook/SKILL.md ~/.codex/skills/logbook/

Any MCP-Compatible Client

Logbook works with any tool that supports the Model Context Protocol. Add this to your client's MCP server configuration:

{
  "logbook": {
    "command": "npx",
    "args": ["@wheeldrop/logbook"]
  }
}

The server uses stdio transport — no network, no API keys, purely local.

Agent Skills (Optional)

Logbook ships a skill file (skills/logbook/SKILL.md) that teaches agents how to search effectively — query formulation, result triage, the search→sessions→read drill-in workflow. Copy it into any agent that supports skills:

• Codex CLI: ~/.codex/skills/logbook/SKILL.md
• Claude Code: Install as a plugin (bundles the skill automatically)
• Gemini CLI: Install as an extension (bundles the skill automatically)

What It Does

WheelDrop Logbook indexes conversation history, memory files, plans, and knowledge artifacts from your local AI coding agent data. It exposes 5 MCP tools:

| Tool | Description | |------|-------------| | logbook_search | Full-text search across all agents with fuzzy matching, filtering by agent/type/date/project | | logbook_sessions | Browse recent sessions sorted by recency | | logbook_read | Retrieve messages from a specific session with context windowing and fuzzy query matching | | logbook_memory | Search CLAUDE.md, GEMINI.md, AGENTS.md, and instruction files | | logbook_plans | Search plan files, brain documents, and knowledge artifacts |

Custom Data Locations

WheelDrop Logbook respects the same environment variables as the agents themselves:

| Agent | Variable | Default | |-------|----------|---------| | Claude Code | CLAUDE_CONFIG_DIR | ~/.claude | | Codex CLI | CODEX_HOME | ~/.codex | | Gemini CLI | GEMINI_CLI_HOME | ~ (.gemini created inside) |

If you use a nonstandard data directory for any agent, set the corresponding variable before running Logbook.

Supported Data Sources

| Agent | Conversations | Memory | Plans | Subagents | |-------|:---:|:---:|:---:|:---:| | Claude Code | history.jsonl + session JSONL | CLAUDE.md (global + per-project) | plans/.md | subagent sessions | | Codex CLI | history.jsonl + date-tree sessions | AGENTS.md + rules/ | — | — | | Gemini CLI | session JSON + logs.json (cleared sessions) | GEMINI.md | plans/.md | — |

Architecture

• Transport: stdio (local only, no network)
• Search: MiniSearch with fuzzy matching and prefix search
• Indexing: Full session content indexed on first search, with score normalization to prevent long-document bias
• Parsers: Modular per-agent, implementing the AgentParser interface

Development

git clone https://github.com/wheeldrop/logbook.git
cd logbook
npm install
npm run build
npm test              # 156 tests
npm run lint          # ESLint
npm run typecheck     # TypeScript strict mode
npm run test:coverage # Coverage with v8
npm run check         # All of the above

Testing with MCP Inspector

npm run inspect

Project Layout

src/
├── parsers/          # Per-agent parsers (claude, codex, gemini)
│   ├── types.ts      # AgentParser interface
│   └── registry.ts   # Parser auto-discovery
├── search/
│   ├── engine.ts     # MiniSearch wrapper with score normalization
│   ├── tokenizer.ts  # Shared tokenizer and fuzzy matching
│   └── types.ts      # Search options and result types
├── utils/            # Shared utilities (time, paths, jsonl, display)
├── install.ts        # --install auto-detection and configuration
├── server.ts         # MCP tool registration
└── index.ts          # Entry point (stdio transport + CLI flags)
skills/               # Codex skill
agents/               # Shared AGENTS.md for Gemini/Codex

Contributing

See CONTRIBUTING.md for development setup and pull request guidelines.

License

Apache-2.0 — Crash United, LLC

See LICENSE for the full text. Contributions require agreement to the Contributor License Agreement.