Metadata-Version: 2.4
Name: chronicle-sdk
Version: 0.2.0
Summary: Local-first run recorder and context layer for AI coding agents.
Project-URL: Homepage, https://github.com/animeshdutta888/chronicle
Project-URL: Repository, https://github.com/animeshdutta888/chronicle
Project-URL: Issues, https://github.com/animeshdutta888/chronicle/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: GitPython>=3.1.43
Requires-Dist: mcp<2,>=1.27
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.8
Provides-Extra: faiss
Requires-Dist: faiss-cpu>=1.8.0; extra == "faiss"
Provides-Extra: hosted
Requires-Dist: fastapi>=0.115; extra == "hosted"
Requires-Dist: uvicorn>=0.30; extra == "hosted"
Provides-Extra: treesitter
Requires-Dist: tree-sitter>=0.25.0; extra == "treesitter"
Requires-Dist: tree-sitter-python>=0.23.0; extra == "treesitter"

# 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.

```bash
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:

```bash
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:

```text
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:

```text
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:

```text
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](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`](docs/demos/flask-context-demo/report.md) and
[`report.html`](docs/demos/flask-context-demo/report.html).

## Run Replay

```bash
chronicle replay --latest
```

Replay prints a timeline:

```text
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:

```bash
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

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

Review artifacts include an Impact Map:

```md
## 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>/`:

```text
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

```bash
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:

```bash
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

```python
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.
