Chronicle Documentation
Chronicle is a local-first time machine for AI coding sessions. It imports the conversation logs your AI coding assistants already write, and maps every message to the exact state of your code at that moment — reconstructed from your project's Git history. Click any message, and travel back to the code as it was.
Everything runs on your machine. There are no LLM calls anywhere, no cloud backend, and your source logs and project repos are never written to. Chronicle observes and organizes your AI tools; it never replaces them.
Chronicle imports from six tools today — Claude Code, Codex, Cursor, OpenCode, Gemini CLI, and GitHub Copilot Chat — and unifies their sessions into a single, path-based project view.
New here? Jump to the Quickstart and reach your first time-travel moment in under five minutes.
The three pillars
Chronicle's design philosophy is Replay · Control · Secure:
- Replay — Time Travel over any session, a deterministic Replay sandbox, Refine for distilling a session into docs or a reusable prompt, and Context Causality linking what the AI read to what it changed.
- Control — a unified control plane for MCP services and Skills across every tool: take over existing configs, centralize them, and distribute them everywhere.
- Secure — one-click Security Check and redaction, real-time pre-tool-use interception, and locally served, redacted share links. All parsing and storage stay on-device (see Privacy & data).
Guide
Get up and running, then explore each feature.
| Page | What it covers |
|---|---|
| Installation | Homebrew, the signed DMG, running from source, and auto-update |
| Quickstart | Your first time-travel in under five minutes |
| Importing sessions | The import wizard, all six sources, and the read-only guarantees |
| Time travel | Playback mode, code snapshots, diff view, and the TimberLine timeline |
| Search & filtering | Type-filter chips, ⌘F search, and the ⌘K command palette |
| Session insights | Overview stats, Active Duration, Cost & Usage, and the context-window bar |
| Refine mode | Distill a session with Keep / Delete / Edit / Insert, then export |
| Replay mode | Deterministic re-execution in an isolated sandbox |
| Project management | Logical projects, association, the Git pill, and sync |
| Context causality | Heuristic read → change linking with confidence tiers |
| Live streaming | Watching in-progress sessions in real time |
| MCP Hub | The aggregating MCP server, config takeover, tool policies, and the Inspector |
| Skills Hub | Central skill storage, symlink distribution, GitHub import, and versioning |
| Security & sharing | Security Check, custom rules, the pre-tool-use hook, and share links |
Reference
| Page | What it covers |
|---|---|
| Keyboard shortcuts | Every shortcut, grouped by mode |
| Compatibility | The six-tool support matrix and per-tool log locations |
| Configuration | The ~/.chronicle/ layout, environment variables, and config.json |
| Privacy & data | The local-first guarantees and the exact outbound calls |
Architecture
For contributors who want to understand and extend the codebase.
| Page | What it covers |
|---|---|
| Overview | Single-process/single-port design, run modes, component map, and principles |
| Data model | The SQLite schema, the normalized event model, and replaceSession |
| Parsers & ingestion | The event model in depth, plus how to add a new source |
| Git snapshot engine | Reconstructing code state from Git history |
| MCP & Skills internals | The registry, the hub, Streamable HTTP, and skill distribution |
| Security, live & replay | The redaction engine, SSE watchers, the replay engine, and causality |
| API reference | Every REST route, the SSE stream, /mcp, and /share |
| Desktop & packaging | The Electron shell, signing, auto-update, and the release flow |
Then see Contributing for dev setup, the branch-and-PR workflow, and how changes are verified.
Project background
Chronicle was built from a detailed product requirements document; its decision log records what shipped versus what was deferred. The README carries the full feature inventory, and the CHANGELOG tracks releases.
License: Chronicle is MIT licensed.