Chronicle

Chronicle is a local-first run recorder and context layer for AI coding agents.

It prepares grounded repo context before an agent codes, captures the diff after it codes, reviews impacted files/tests, and creates a replayable handoff for the next human or agent.

pip install chronicle-sdk

chronicle setup codex
chronicle run "Fix auth token refresh bug"

# let Codex / Claude / Cursor make changes

chronicle finish --base main
chronicle replay --latest

Chronicle helps teams answer:

• What context did the agent use?
• Which files and symbols were impacted?
• What changed?
• What tests should be run?
• What should the next agent or reviewer know?

Alpha release: Chronicle is currently strongest on Python .py repositories. Non-Python repositories still get basic file/diff risk coverage.

v0.2: Agent Run Recorder

Chronicle v0.2 is built around one loop:

chronicle run "Add retry handling to payment webhook"
# agent edits code
chronicle finish --base main
chronicle report --latest
chronicle report --latest --html
chronicle replay --latest

chronicle run prepares an Agent Run:

Chronicle Agent Run prepared

Context prepared: yes
Agent prompt saved: chronicle_logs/runs/run_x/agent_prompt.md
Key files: 6
Impacted symbols: 14
Suggested tests: 3
Risk areas:
- payments/webhook.py is billing-sensitive.

chronicle finish closes the loop:

Chronicle Agent Run finished

Changed files: 4
Impacted symbols: 7
Review findings: 2
Report saved: chronicle_logs/runs/run_x/report.md

The Run Report

Every finished run writes one polished handoff artifact:

chronicle_logs/runs/<run_id>/report.md
chronicle_logs/runs/<run_id>/report.html

The report includes:

• Task
• Context Used
• Agent Changes
• Impact Map
• Review Findings
• Suggested Next Prompt
• Handoff
• Context Quality Score
• Token budget and token savings
• Saved artifacts

The HTML report is static, local, and read-only. It is meant for screenshots, demos, PR handoffs, and recruiter-friendly walkthroughs without running a dashboard.

Demo: Flask Context Change

Chronicle includes a real README-ready demo recorded against the open source Flask repo: docs/demos/flask-context-demo.

The run asked Chronicle to add a small explanatory comment near Flask request context handling without changing behavior. Chronicle selected src/flask/app.py and src/flask/ctx.py, prepared a 1,487-token context packet from an estimated 13,531-token repo context, and recorded an 89.01% token reduction.

After the agent made a one-line comment-only change in src/flask/ctx.py, Chronicle captured diff.patch, generated an Impact Review with suggested tests, saved a Run Replay timeline, and rendered both report.md and report.html.

Run Replay

chronicle replay --latest

Replay prints a timeline:

Chronicle Run Replay

Run: run_20260604_abc123
Task: Fix auth token refresh bug
Status: finished

1. PREPARE
   Query: Fix auth token refresh bug
   Context files: 6
   Token budget: auto
   Prompt saved: chronicle_logs/runs/run_x/agent_prompt.md

2. AGENT WORK
   Diff captured: chronicle_logs/runs/run_x/diff.patch
   Changed files: 4

3. REVIEW
   Findings: 2
   Related tests: 3

4. HANDOFF
   Report: chronicle_logs/runs/run_x/report.md
   HTML: chronicle_logs/runs/run_x/report.html

Code Memory

Use inspect when you want codebase intelligence without starting an agent run:

chronicle inspect --file src/auth/service.py
chronicle inspect --symbol AuthService.refresh_token

Symbol inspection shows where a symbol is defined, who calls it, what it calls, imports, related tests, and recent git changes. File inspection shows indexed symbols, imports, incoming references, related tests, and recent changes.

Impact Review

chronicle review
chronicle pr-review --base main
chronicle pr-review --base main --output pr-review.md

Review artifacts include an Impact Map:

## Impact Map

Changed:
- src/auth/service.py::refresh_token

Likely impacted:
- src/api/auth_routes.py::refresh
- tests/test_auth_refresh.py

Risk:
HIGH - auth/session lifecycle changed

Suggested tests:
- python -m unittest tests.test_auth_refresh

Artifacts

Chronicle saves local artifacts under chronicle_logs/runs/<run_id>/:

prepare.md
context_packet.md
agent_prompt.md
diff.patch
review.md
pr-review.md
report.md
report.html
prepare.json
review.json
pr-review.json
run.json

Use agent_prompt.md as the ready-to-paste prompt for Codex, Claude, Cursor, or another coding agent.

Agent Setup

chronicle setup codex
chronicle setup claude
chronicle setup cursor
chronicle setup all
chronicle setup codex --no-mcp
chronicle setup codex --mcp-only

Setup adds Chronicle workflow instructions and attempts MCP registration:

• Codex: appends AGENTS.md and runs codex mcp add chronicle -- chronicle-mcp --repo <repo> when codex is installed.
• Claude: appends CLAUDE.md and runs claude mcp add chronicle -- chronicle-mcp --repo <repo> when claude is installed.
• Cursor: writes .cursor/rules/chronicle.mdc and project .cursor/mcp.json.

If Codex or Claude is not installed, setup still updates the workflow file and prints the manual MCP command.

MCP

Start a Chronicle MCP server for one repo:

chronicle-mcp --repo /path/to/repo

For v0.2, the main MCP workflow is:

• chronicle.prepare - create a Context Packet for a coding task.
• chronicle.review - review current code changes and impacted tests.
• chronicle.handoff - create a handoff packet from prepare/review state.
• chronicle.replay/status - inspect saved runs and repo readiness.
• chronicle.inspect - inspect files and symbols.

Advanced MCP tools such as evaluation, call-chain tracing, sessions, and multi-agent bus helpers remain available, but the product path is inspectable coding-agent runs.

SDK

from chronicle import Chronicle

chronicle = Chronicle(repo_path="./repo")

run = chronicle.run("Fix auth token refresh bug")
# agent edits code
finished = chronicle.finish(base="main")
report = chronicle.report(latest=True)

print(run["saved"]["agent_prompt_md"])
print(finished["saved"]["report_md"])
print(report["report"])

Product Names

Benchmark Snapshot

These are deterministic local workflow checks from the test suite, not broad model-quality claims.

Release Notes

Chronicle v0.2 makes AI coding work inspectable, replayable, and handoff-ready.

What changed:

• chronicle run is now the primary workflow entrypoint.
• chronicle finish captures diff, review, PR review, Markdown report, and static HTML report.
• chronicle report --latest --html prints/regenerates the local HTML run report.
• chronicle replay --latest prints a four-phase run timeline.
• Impact Review adds an explicit Impact Map.
• Code Memory improves inspect --file and inspect --symbol.
• Git history parsing now preserves recent file changes for inspection.

Notes

• Chronicle is local-first and does not send repository code anywhere by default.
• Index artifacts are stored in chronicle_logs/index.sqlite3 unless --index-dir is provided.
• Remote repos cloned via --repo-url are stored in chronicle_logs/repos/ by default.
• Token savings are still reported, but they are a benefit of grounded context, not the product story.