Annalist

Local flight recorder for agent runs. Wrap a coding agent, review observed file changes in a private loopback dashboard, preview recovery before restoring. No account, telemetry, or cloud.

github.com/GregDixonMXN/annalist · Zig + SQLite · 1.0.0 · Linux x86_64

Railpane role

Railpane receipt carries annalist_session_id. Annalist answers "what actually happened to the working tree?"; Railpane answers "who authorized it, under which policy, for which agent and task?" Separate concepts, linked — never one undifferentiated audit store.

Get running

zig build -Doptimize=ReleaseSafe
install -Dm755 zig-out/bin/annalist "$HOME/.local/bin/annalist"
cd /path/to/project
annalist init
annalist run -- codex     # or: annalist run -- claude
annalist ui               # http://127.0.0.1:8901

Review and recover

annalist sessions
annalist inspect 1
annalist inspect 1 --json
annalist diff 1 2
annalist rewind 1 --dry-run
annalist rewind 1
annalist export 1 --out ../run-1

Rewind restores only paths touched by that run. Stop agents/editors first. Pre-recovery copies kept in .annalist/recovery/ with manifest.

CI policy gate

annalist gate --session 1 --policy annalist.policy.toml
# exit 0 pass, 2 deny, 1 broken
# annalist.policy.toml:
allow_paths = ["src/", "docs/", "tests/"]
deny_globs = [".env", ".env.*", "*.pem", "**/secrets/**"]
max_files_changed = 80
fail_on_secret = true

GitHub Action available upstream; mark required under branch protection so a .env-writing PR cannot merge. File contents stored unredacted — review exclusions (.annalist/config.toml) first.