Chronicle

A searchable memory of every coding-agent session you run.
Claude Code, Codex, GitHub Copilot and IBM Bob sessions and your claude.ai and ChatGPT chats, kept and turned into knowledge on your own machine.

Quick start · Docs · Changelog · 日本語

Your coding agents solve problems all day, and then the lesson disappears: Claude Code deletes transcripts after 30 days, and nothing carries a fix from one session to the next. Chronicle keeps every session, uses Claude Code or Codex to pull out what was learned, and gives it back to you in a dashboard and to your agents through an MCP server.

What it gives you

Chronicle reads each finished session and writes down what is worth keeping. A real example, taken word for word from the demo data:

Gotcha · billing-api
Stripe webhook signatures need the raw request body
Webhook.construct_event verifies the signature over the exact bytes Stripe sent. Parsing to JSON first, or posting json= in tests, fails with SignatureVerificationError. Read await request.body() and pass that.
_{From the session "Stop double charges when Stripe retries invoice.paid", extracted automatically.}

• Every session, kept for good. Raw transcripts are archived, so nothing is lost when an agent cleans up.
• Knowledge, extracted automatically. Fixes, gotchas, decisions, commands, project facts and preferences, merged into a knowledge base per project and a playbook across all of them.
• Your agents can ask. Through the MCP server, an agent can search your past sessions: "have we hit this error before?", "why did we put idempotency in Postgres?" Claude Desktop, Cursor, Windsurf and Gemini CLI can connect too.
• A dashboard to browse it all. Sessions with their full transcripts, statistics, a glossary of your own vocabulary drawn as a mindmap, and a weekly review you can take in at a glance. ⌘K jumps anywhere.
• Plain files too. An Obsidian-compatible Markdown vault and a chronicle CLI.

Quick start

You need macOS 13 or later and a logged-in Claude Code or Codex, which does the analysis.

1. Install.

   uv tool install --python 3.13 agents-chronicle   # or: pipx install agents-chronicle
   chronicle install
   

   chronicle install finds the coding agents on your Mac, asks which to record, imports their past sessions and asks whether to run Chronicle from login. For the app instead, download it from the latest release (Apple silicon) and choose Connect.

2. Use your agents as usual. Each session is recorded when it ends and analyzed in the background.

3. Explore. Open the dashboard at http://127.0.0.1:8765/ (or chronicle ui --open) and press ⌘K, or ask your agent what it learned last week.

Connect more agents later from Settings › Sources, chronicle connect <agent>, or by re-running chronicle install. Install covers what each step sets up and how to remove it.

Supported agents

All of them share one dashboard, knowledge base, glossary and set of MCP tools; analysis runs through Claude Code or Codex, whichever you choose. Sources has the details for each.

A closer look

Home. Active time, sessions, tokens and estimated cost, day by day.	Map. Your glossary as a mindmap; each term opens into the knowledge and sessions behind it.	⌘K. One search over sessions, knowledge, projects, terms and commands.

Screenshots use made-up demo data.

How it works

1. A hook (or the 15-minute sync) hands each finished session to Chronicle, which archives the raw transcript and parses it: prompts, replies, tool calls, files, tokens and cost.
2. Once the session is idle, a condensed digest with secrets redacted goes to Claude Code (claude -p) or Codex (codex exec), whichever you chose, which returns a summary and knowledge items. The call runs sandboxed: no tools, hooks or MCP servers.
3. New knowledge is merged into the project's knowledge base, the glossary is refreshed, and each finished week gets a written review.
4. Everything is served to you (dashboard, app, vault, CLI) and to your agents (MCP).

What leaves your machine: only that redacted digest, sent to Anthropic or OpenAI through your own Claude Code or Codex login. No telemetry, nothing sent to anyone else. Data and privacy lists what is stored where.

What it costs: analysis draws from your Claude or ChatGPT plan like any other use of the agent. With Claude, in API terms it averages about $0.38 per session with Sonnet; chronicle analyze --pending --dry-run sizes a backlog before you spend anything. How analysis works has the details.

FAQ

Will it slow down my agent? No. The session-end hook hands off to a detached process and returns in milliseconds; analysis runs later in the background.

Do I need Claude Code? No. Analysis runs through Claude Code or Codex: pick one in Status › Analysis or with chronicle config set analysis.backend codex. Recording and browsing work either way; with neither signed in, sessions are archived and wait in the analysis queue.

Windows or Linux? Not yet. The app and the background agents are macOS only.

Can I keep a project or a session out? Add the project to sources.exclude_projects in the configuration, or remove a session for good with chronicle forget <id>.

How do I remove it? chronicle uninstall removes the hooks, background agents and MCP registrations and keeps your data; add --purge to delete the data too.

Something not working? See Troubleshooting.

Documentation

Install · Sources · Dashboard, glossary and Map · Command line · MCP server · What gets recorded and how analysis works · Configuration · Data and privacy · Troubleshooting · Development

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md explains how to run the tests and work on the dashboard with demo data instead of your own sessions.

License

MIT