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
handoff.md
prepare.json
review.json
pr-review.json
handoff.json
run.json

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

Agent Handoff

Use handoff when a human or another agent needs to continue from the current run:

chronicle handoff \
  --tests "python -m unittest tests.test_auth_refresh passed" \
  --note "OAuth provider edge cases still need manual verification"

Chronicle writes:

chronicle_logs/runs/<run_id>/handoff.md
chronicle_logs/runs/<run_id>/handoff.json

The handoff includes:

• repo status and changed files
• prepared context summary
• review summary
• tests run or still missing
• explicit notes for the next human or agent
• warnings when prepare/review/test coverage is incomplete

Example:

# Chronicle Handoff

## Repo Status
- Index status: ready
- Changed files: src/auth/service.py

## Prepared Context
- Files: src/auth/service.py, src/auth/models.py
- Warnings: none

## Review Context
- Related tests: tests/test_auth_refresh.py
- Warnings: No test files changed.

## Tests
python -m unittest tests.test_auth_refresh passed

## Notes
- Verify OAuth provider edge cases before merge.

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

Chronicle ships an MCP server so Codex, Claude, Cursor, or another MCP client can ask Chronicle for grounded repo context without leaving the agent.

Start a Chronicle MCP server for one repo:

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

Manual Codex registration:

codex mcp add chronicle -- chronicle-mcp --repo /path/to/repo

Use the local checkout instead of an installed package:

codex mcp add chronicle -- env PYTHONPATH=/path/to/chronicle/src \
  python3 -m chronicle.mcp_stdio \
  --repo /path/to/repo

Project-specific example:

codex mcp add chronicle-nudge -- chronicle-mcp \
  --repo /Users/you/Projects/Nudge_git/Nudge

Check the registration:

codex mcp list
codex mcp get chronicle

MCP Workflow

The best v0.2 MCP loop is:

1. Agent calls `prepare` for the coding task.
2. Agent edits using the returned Context Packet.
3. Agent calls `review` after editing.
4. Agent calls `handoff` with test results and notes.
5. For full `diff.patch`, `report.md`, `report.html`, and replay, run `chronicle finish` / `chronicle replay` from the CLI.

Prompt an MCP-enabled agent like this:

Use Chronicle MCP for this repo.

Prepare context for:
"Fix auth token refresh bug."

Use only the returned context unless you need more files. After editing,
call Chronicle review and handoff with the tests you ran. If a final HTML
run report is needed, run `chronicle finish --base main`.

Main MCP Tools

These are the tools most users should start with:

• index - build repository intelligence.
• prepare - create a Context Packet for a coding task.
• status - inspect index, changed files, and latest artifacts.
• review - review current code changes and impacted tests.
• handoff - write an Agent Handoff from prepare/review/test state.

Useful advanced tools:

• context - retrieve grounded context without creating the full prepare artifact.
• call_chain - build a functional call chain for a repo question.
• doctor - diagnose indexing and retrieval readiness.
• evaluate - compare Chronicle context against broader baseline context.
• prepare_prompt_packet - produce an SDK-ready prompt packet.
• session_start / session_show - use Workflow Memory.
• bus_start, bus_context, bus_handoff, bus_show, bus_validate_latest, bus_summary - advanced multi-agent bus workflows.

The CLI currently owns the full Agent Run recorder loop (run, finish, report, replay). MCP owns agent-accessible context, review, and handoff. In practice they work together: MCP prepares and reviews while the CLI captures the final diff and HTML report.

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

Capability	Product name
prepare	Context Packet
run + finish	Agent Run
review / pr-review	Impact Review
replay	Run Replay
handoff	Agent Handoff
inspect	Code Memory
session memory	Workflow Memory

Benchmark Snapshot

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

Scenario	What Chronicle verifies	v0.2 status
Agent run loop	run -> finish -> report -> replay artifacts	Passing
Static report	report.md and report.html generated locally	Passing
Impact Review	changed files, impacted symbols, suggested tests	Passing
Code Memory	file/symbol inspect with related tests and recent changes	Passing
Non-Python fallback	basic file/diff risk report for non-Python repos	Passing

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.