events — the unified decision log

One append-only file per project, one JSON line per decision. Nothing else in the pipeline needs to change what it does — it just also calls log_event.

python -m skills.events.cli tail .           # last 20 events
python -m skills.events.cli tail . -n 50 --json
python -m skills.events.cli log route . --field out=local --field tokens_saved=210
python -m skills.events.cli clear .

from skills.events import log_event, read_events, tail_events, follow_events

log_event("route", project_root=".", filter=1, out="local", tokens_saved=210)
tail_events(".", n=20)
for rec in follow_events("."):   # blocking generator, for --live tools
    ...

Event kinds

kind is free-form — any skill can log its own label; the table above is just what the showcase tools (demo mode, dashboard --watch, replay) render by default.

Design

• Best-effort, never raises. A logging failure must never break the caller — same contract as control_loop.record.
• Rotation at 5 MB, keeps the newest half — same spirit as .botte-cache/.
• 0 tokens, 0 network. Pure stdlib, local file only — consistent with the project's "no telemetry" guarantee: this file never leaves the machine.
• Project-scoped (.botte/events.jsonl), unlike control_loop's ~/.botte/control-ledger.jsonl which is machine-wide — events are about this project's live activity, the ledger is about tuning the router globally over time.

Related: [[control_loop]] (the other ledger), [[dashboard]], [[cache]].