aichronicles

Capture your AI coding sessions, locally, with secrets scrubbed before they hit disk.

Status: work in progress.

aichronicles runs as a tiny user-mode daemon that ingests hook events from Claude Code and Gemini CLI into a SQLite store, exposes the corpus as an MCP server your agent can query for context from past work, and generates structured summaries on demand.

flowchart LR
    cc[Claude Code]
    api[(Anthropic / OpenAI<br/>HTTPS, on-demand)]

    subgraph local["Your machine — single user, local disk"]
        direction LR
        ingest["aichronicles ingest<br/><i>hook subprocess</i>"]
        daemon["aichroniclesd<br/><i>systemd --user · UDS 0600</i>"]
        db[("SQLite store<br/>raw_envelopes ▸ events ▸<br/>extractions ▸ llm_outputs")]
        mcp["aichronicles mcp-serve<br/><i>stdio</i>"]
        cli["aichronicles summarize<br/>/ reflect / propose"]
    end

    cc -- "hook fires" --> ingest
    ingest -- "edge redact<br/>POST /v1/ingest" --> daemon
    daemon -- "verify + persist" --> db
    cc <-- "tools/call (stdio)" --> mcp
    mcp -- "read-only SQL" --> db
    cli -- "read events + cache" --> db
    cli -.->|"egress redact ▸ tool use"| api
    api -.-> cli
    cli -- "write llm_outputs" --> db

Loading

Legend. Solid arrow: data flows in this direction. Dashed arrow: optional / on-demand (only fires for summarize/reflect/propose). The local box is the trust boundary — everything inside runs as your user, on your local disk. Cylinder is persistent state.

What you get

• Searchable corpus. Every prompt, tool call, and response from your Claude Code sessions, indexed by SQLite FTS5. aichronicles search 'mongodb shutdown' returns the turn where you fixed it.
• Structured summaries. aichronicles summarize --session <id> produces a JSON record with topic, what-was-done, unresolved items, files touched, and links you actually referenced — annotated with what you used each one for. Cached in the store; replays for free.
• Cross-session reflection. aichronicles reflect and propose read recent sessions and surface recurring task types, friction sources, and concrete capabilities (skills, CLAUDE.md rules, scripts) worth pre-building.
• MCP exposure. aichronicles mcp-serve registers as an MCP server in Claude Code, so the agent can search your past sessions and pull a prior summary mid-conversation.
• Edge-scrubbed. Secrets matching ~15 patterns (Anthropic/OpenAI/AWS/etc.) are redacted to <redacted:kind> markers before envelopes leave the hook subprocess. The daemon refuses unredacted envelopes as defense-in-depth.

Example: aichronicles summarize

Topic: feat(grass): prefer stereo version_data over GitHub tags

What was done:
  - Added stereo.go to agents/pkg/agents/grass/ with YAML structs
    for version_data/*.yaml and a lookupStereoVersion scanner.
  - Extended grass.Analyze with a variadic opts API (WithStereoDir)
    that overrides the GitHub-tag version when stereo data matches.
  - Wired the option through the manifest-gen pipeline; added a
    --stereo-dir flag to the cg agent grass CLI command.

Unresolved:
  - cg-codeowners-check still pending — awaiting human review.
  - Reconciler config struct lacks test coverage for the new field.

Key files:
  - agents/pkg/agents/grass/stereo.go
  - bots/manifest-gen/internal/agent/analyzer/analyzer.go
  - cg/pkg/commands/agent.go

Links:
  - https://github.com/chainguard-dev/customer-issues/issues/3406
    source ticket for the harbor cert work

Status

Personal-use software, single-machine. Designed for one developer running Claude Code on their own laptop or workstation. No multi-user authentication, no central server, no remote backup. The threat model is documented at docs/explanation/threat-model.md; read it before adopting if you handle anything sensitive.

Supports two source agents today: Claude Code (Anthropic) and Gemini CLI (Google). Both write hooks into their respective settings file via aichronicles setup <agent> and ingest live through the same UDS daemon. The envelope schema, redaction layer, and MCP server are agent-agnostic; adding another agent's hook format is mostly importer work.

Get started

Quick start (≤90 seconds) — install, bring up the daemon, see your first hook event captured.

Your first summary — configure an API key and generate a structured summary of one session.

Documentation

Section	What's there
Tutorials	Learn by doing
How-to guides	Recipes for specific tasks
Reference	CLI, configuration, schema, detectors (auto-generated)
Explanation	Architecture, data flow, threat model, design decisions

Building from source

git clone <repo-url> && cd aichronicles
go build ./...
go test ./...
go test -tags=integration ./integration/...

Targets the toolchain in go.mod (Go 1.26+). Five direct deps: modernc.org/sqlite (pure-Go SQLite), spf13/cobra, BurntSushi/toml, google/uuid, godbus/dbus/v5; plus the official Anthropic and OpenAI SDKs.

License

Apache-2.0 is the planned license. The LICENSE file lands in the first public-release commit; until then, the code is shared under no formal terms.

Contributing

The development practices (commit style, testing rules, idiomatic Go expectations) are in CLAUDE.md. Read it before opening a PR.