events — the unified decision log

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

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 stats .          # summary of kinds, savings, tool calls
python -m skills.events.cli export . -o events.csv # CSV export for offline analysis
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/.
• Local-file logging design. Check the installed logger and any export or forwarding configuration. A local file does not itself guarantee that an agent or connected service cannot transmit its content.
• 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]].