Breadcrumbs

Claude Code already saves every session to disk as JSONL transcript files. You just can't easily browse or search them.

Breadcrumbs changes that:

• Indexes all your history into SQLite — install.py bulk-imports every existing session across all projects. SQL queries, full-text search, cross-project analysis — all instant instead of parsing flat files.
• Keeps it current with hooks — every new prompt and response is recorded automatically. The database stays in sync with your active sessions, even across multiple Claude Code instances.
• Browse it in your browser — server.py serves a local web UI with a session list, conversation viewer, and project filtering.
• MCP endpoint for agents — any MCP-capable agent can query your entire development history: "what bugs did we fix last week?", "how did this architecture evolve?", "what patterns repeat across projects?". Project diaries, decision logs, knowledge extraction — all from data you're already generating.

The raw material has been there all along. Breadcrumbs just makes it accessible.

Inspired by Shelley's approach to recording agent sessions in SQLite.

Requirements

• Python 3.6+
• Claude Code

No additional packages needed — stdlib only.

Install

git clone https://github.com/davidg238/breadcrumbs.git
cd breadcrumbs
python3 install.py

Then restart Claude Code.

Uninstall

cd breadcrumbs
python3 uninstall.py

The database is preserved after uninstall. Delete ~/.claude/breadcrumbs.db manually to remove all data.

How It Works

Two Claude Code hooks record session data:

• UserPromptSubmit — records your prompt immediately (crash insurance)
• Stop — syncs the full transcript to SQLite after each Claude response

Data is stored in ~/.claude/breadcrumbs.db with three tables:

Table	Contents
sessions	One row per session — project, cwd, model, git branch, timestamps
messages	Every message — prompts, responses, tool calls, results
message_images	Screenshots and images extracted from messages

Viewer

Browse sessions in your browser:

python3 server.py                    # start viewer
python3 server.py --open             # also open browser
python3 server.py --port 9000        # custom port
python3 server.py --tailscale        # bind to this node's Tailscale IP

By default the viewer binds to 127.0.0.1 (this machine only). To reach it from other devices on your Tailscale tailnet, bind to this node's Tailscale IP:

python3 server.py --tailscale

This binds to the Tailscale interface only — not your regular LAN. Note the viewer exposes your full session history to any device on the tailnet.

Features:

• Session list grouped by project, with search and keyboard navigation
• Conversation view with user/assistant messages, collapsible tool calls
• Inline image display with expand/collapse toggle
• Token usage per session (input, output, cache)
• Device-local usage banner with rolling-window token totals
• Projects table with Sess 5h / Sess wk / Sess total columns, grouped by activity (Active last 5h / Active this week / Older). Click any column header to sort the whole table; a "Group by activity" link restores the grouped view.
• Editable session names (click the name in the status bar)
• Keyboard: / to search, Up/Down to navigate sessions, Escape to blur

Usage banner

The project summary shows a device-local usage banner with two rolling windows — Current session (5 hours) and All models (7 days) — computed from the token counts already stored in ~/.claude/breadcrumbs.db. Totals and the approximate reset countdown are always exact for this machine.

To also show an approximate /usage-style percentage, create ~/.claude/breadcrumbs_usage.json:

{
  "session_budget": 100000,
  "weekly_budget": 2000000,
  "model_weights": { "default": 1.0, "claude-opus-4-8": 5.0 },
  "billable": "output_plus_input"
}

• session_budget / weekly_budget — weighted-token budgets. 0 (default) hides the percentage.
• model_weights — per-model multiplier (default applies to unlisted models).
• billable — output_only | output_plus_input (default) | all.

The percentage is a local estimate — Anthropic's real plan limits are undocumented. Calibrate by nudging the budgets until the percentage matches what Claude Code's /usage shows, then it will track.

Run as a Service (Linux)

To have the viewer start automatically at login and run in the background, install it as a systemd user service.

Create ~/.config/systemd/user/breadcrumbs.service:

[Unit]
Description=Breadcrumbs Viewer (Claude Code session history)
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/python3 %h/path/to/breadcrumbs/server.py --port 8765
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Replace %h/path/to/breadcrumbs with the absolute path to your clone. Then:

systemctl --user daemon-reload
systemctl --user enable --now breadcrumbs.service
loginctl enable-linger $USER       # keep it running when logged out (may need sudo)

Manage it:

systemctl --user status breadcrumbs
systemctl --user restart breadcrumbs
journalctl --user -u breadcrumbs -f

The server binds to 127.0.0.1 only — not reachable over the network.

macOS: use launchd with a ~/Library/LaunchAgents/com.breadcrumbs.plist file instead. Windows: use Task Scheduler with trigger "At log on", or run server.py via pythonw.exe from the Startup folder.

MCP Endpoint

The viewer includes an MCP server at http://localhost:8765/mcp (shown on the landing page). Any MCP-capable agent can query your session history.

Setup: Add to ~/.claude/settings.json (with server.py running):

{
  "mcpServers": {
    "breadcrumbs": {
      "type": "url",
      "url": "http://localhost:8765/mcp"
    }
  }
}

Available tools:

Tool	Description
list_projects	All projects with session counts and date ranges
list_sessions	Sessions filtered by project, date range; optional include_previews
get_session_messages	Messages for a session; supports limit / offset (negative offset = tail)
search_messages	Full-text search; optional session_id scope
get_stats	Aggregate stats: tokens, top tools used

Querying

sqlite3 ~/.claude/breadcrumbs.db

Example queries:

-- All sessions, most recent first
SELECT session_id, project, started_at FROM sessions ORDER BY started_at DESC;

-- Messages from a specific session
SELECT type, role, substr(content_text, 1, 100), timestamp
FROM messages WHERE session_id = '...' ORDER BY sequence;

-- All tool usage across projects
SELECT tool_name, COUNT(*) as uses
FROM messages WHERE tool_name IS NOT NULL
GROUP BY tool_name ORDER BY uses DESC;

-- Sessions with screenshots
SELECT DISTINCT s.session_id, s.project, s.started_at
FROM sessions s
JOIN messages m ON m.session_id = s.session_id
JOIN message_images i ON i.message_uuid = m.uuid;

-- Full text search across all prompts
SELECT session_id, content_text, timestamp
FROM messages WHERE type = 'user' AND content_text LIKE '%search term%';

Files

session_recorder.py  — the recording script (copied to ~/.claude/hooks/ on install)
server.py            — web viewer (run manually to browse sessions)
install.py           — sets up hooks in Claude Code settings
uninstall.py         — removes hooks, preserves database

TODO / Limitations / Notes

• Operating Systems: This tool has currently only been formally tested on Ubuntu 24.04 (Linux). However, because it relies wholly on Python's standard library, it should work on macOS and Windows as well.
• UI Limitations: The web interface currently lacks session management features. It is not possible to delete sessions, clear history, or rename/favorite sessions directly from the UI (besides editing the current session name).
• Security Concerns: The server.py web server lacks authentication and binds strictly to localhost (127.0.0.1). While this prevents access from the wider network, if run on a shared development machine or remote server, any other user logged into that same machine can access your chat history without authenticating.