--- slug: "bonfire" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/vieko/bonfire@main/README.md" repo: "https://github.com/vieko/bonfire" source_file: "README.md" branch: "main" --- # Bonfire

Bonfire

Session context persistence for AI coding. A file convention + per-host adapters. Pick up exactly where you left off, across sessions, agents, and machines. ## The convention ``` /.bonfire/ ├── index.md └── .gitignore (optional — gitignore if you want per-machine memory; commit if you want cross-machine) ``` `index.md` contains two managed fence blocks: ```markdown # my-repo ## In flight _Updated 2026-05-20 from pi:13e47a9f on `vieko/lead-bot-ash-migration`_ ### Goal PR #147 review prep + GTMENG-1182 calibration ### Next Steps 1. Address inline feedback on classifier 2. Run preflight calibration once classifier is stable ## Sessions - 2026-05-20 [pi:13e47a9f] vieko/lead-bot-ash-migration — PR #147 review + calibration - 2026-05-19 [claude:9a8f1d2e] main — Update AGENTS.md PR convention ``` Everything outside the fences is yours to curate. Anything inside is managed by a bonfire adapter. The canonical curated heading is `## Notes` — the place for free-form context that complements the auto-managed `## In flight` block (open intents, project decisions, runbooks). Sessions are different: they cap at 5 newest rows inside the fence; older entries overflow to a sidecar (`log.md`), not to an in-file `## Session archive` heading. Bonfire is opinionated about not accumulating session prose in `index.md` — see [skills/bonfire/commands/migrate.md](https://github.com/vieko/bonfire/blob/HEAD/skills/bonfire/commands/migrate.md) if you're upgrading a pre-v7 file with paragraph-shaped session entries. ## Install an adapter ### Pi ```bash pi install git:github.com/vieko/bonfire@v7.1.0 ``` (Use `@main` to follow latest, or pin to any tagged version.) Hooks `session_compact` (rich structured summary) + `session_shutdown` (first-user-prompt fallback). Footer status, collision-resistant session ids, opt-in per repo. See [pi/](https://github.com/vieko/bonfire/tree/HEAD/pi/). ### Claude Code Add to `~/.claude/settings.json` (paste, no install script): ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "node /path/to/bonfire/claude/update-bonfire.mjs" } ] } ] } } ``` Reads `{type: "ai-title"}` entries directly from the session JSONL. Idempotent across turns. See [claude/](https://github.com/vieko/bonfire/tree/HEAD/claude/). ### Other agents (Codex, OpenCode, …) Use the cross-agent fallback skill: ```bash npx skills add vieko/bonfire /skill:bonfire end # invoke manually at session end ``` See [skills/bonfire/](https://github.com/vieko/bonfire/tree/HEAD/skills/bonfire/). When the skill runs under Pi 0.82.0+, it uses Pi's bash-tool session env vars (`PI_SESSION_ID`, `PI_SESSION_FILE`) to derive the exact same short session id as the native adapter (so rows de-dupe instead of duplicating) and to read the session JSONL directly. On other hosts — or older Pi — it degrades to the generic rules in [end.md](https://github.com/vieko/bonfire/blob/HEAD/skills/bonfire/commands/end.md). ## Enable per repo Adapters honor an opt-in gate — they never auto-create `.bonfire/` in random repos: ```bash cd mkdir .bonfire ``` Disable per repo: ```bash rm -rf .bonfire ``` Or keep `.bonfire/` but disable automation only: ```bash echo '{ "auto": false }' > .bonfire/config.json ``` ## Why? AI agents are stateless. Every conversation starts from scratch. The agent doesn't remember what you decided yesterday, why you chose that architecture, or where you left off. Bonfire maintains a living context document — read at session start, updated at session end. No external services. No ritual. Just a markdown file in your repo, kept current by per-host adapters or by the agent itself. ## Design The three layers serve different audiences: - **File convention** — works for everyone reading the repo, including humans, future-you, and any AI agent. It's just markdown. - **Host adapters** (`pi/`, `claude/`) — opinionated TypeScript/JS that uses each host's native hook surface. Zero ritual once installed. - **Fallback skill** (`skills/bonfire/`) — outcome-oriented spec for agents that lack a native adapter. The agent figures out the procedure. The adapter writes inside the fence markers and never touches anything else. Your prose, your sections, your headings are yours. ### What lives in `.bonfire/` `index.md` is the only required file. Everything else inside `.bonfire/` is yours — it's gitignored by default and serves as the personal sidecar dir for the repo. Common patterns: ``` .bonfire/ ├── index.md # required; fence-managed by the adapter ├── BACKLOG.md # optional; un-ticketed personal follow-ups ├── KNOWLEDGE.md # optional; durable repo-specific notes (esp. on shared repos where the team's AGENTS.md is off-limits) ├── log.md # optional; older Sessions rows overflowed from the fence cap, or pre-v7 session narratives written by the migrate command └── config.json # optional; per-repo settings, e.g. { "auto": false } ``` The sidecar pattern is especially useful for **shared repos** (any repo you don't own): the team's `AGENTS.md` is for the team, but your personal architectural notes, debugging context, and follow-up lists need a home. `.bonfire/` is that home. Stay disciplined though. The 21 MB cautionary tale: a `.bonfire/` that accumulates audit JSON dumps, ticket-named spec dirs for shipped work, and trim-archive files is a workspace turned graveyard. Periodically prune. If something graduates into team-shared knowledge, promote it to the right canonical home (`docs/`, team `AGENTS.md`, Linear, an RFC) and delete the local copy. ## Requirements - A git repo (the opt-in gate looks for `/.bonfire/`) - An adapter (preferred) or an Agent Skills-compatible tool (for the fallback skill) ## Credits Animation by [Jon Romero Ruiz](https://x.com/jonroru). ## License MIT © [Vieko Franetovic](https://vieko.dev)