bonfire

KO | EN

gitlite — search

#react #ai #llm #go #machine-learning #rust #linux #nodejs #java #awesome #cli #kubernetes #security #open-source

(★ 10)

Cross-session, cross-agent memory for AI coding. Your tools forget, but Bonfire remembers.

bonfire Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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

```
<git-root>/.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](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/](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/](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/](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](skills/bonfire/commands/end.md).

## Enable per repo

Adapters honor an opt-in gate — they never auto-create `.bonfire/` in random repos:

```bash
cd <your-repo>
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 `<git-root>/.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

bonfire

bonfire Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

bonfire

bonfire Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README