bonfire-cli
v1.1.0
Published
A tool to save and recall AI coding session context.
Readme
Bonfire CLI 🔥
Bonfire is a non-intrusive context checkpoint & recall tool for AI coding agents. It allows agents to save and recall session context, progress, and next steps in a .bonfire/ folder at the root of your repository without bloating or clouding the LLM's context window with irrelevant information.
Installation
npm install -g bonfire-cliOr run via npx:
npx bonfire-cli <command>Commands
recall [query] / latest [query]
Recalls session context. When a topic is supplied, Bonfire performs fuzzy & keyword relevance search across checkpoint tags, git branch, message titles, and body content. Only relevant checkpoints are returned; if nothing matches, Bonfire keeps context clean and reports no matches.
# Search for relevant context before starting a task (non-intrusive)
bonfire recall "authentication tokens"
# Output only the compact metadata summary to save token budget
bonfire recall "auth" --summary
# Retrieve the high-level macro cluster summary (Spotify-inspired hierarchical recall)
bonfire recall "auth" --cluster
# Recall the latest session checkpoint
bonfire latest
# Quick summary of the latest checkpoint
bonfire latest --summary
# Output in JSON format for automated agents or scripts
bonfire recall "migrations" --jsonOptions:
-n, --limit <number>: Maximum number of matching checkpoints to return (default:1).-s, --summary: Display compact one-line summary and metadata instead of the full body.-c, --cluster: Retrieve the matched macro cluster / epic summary instead of raw checkpoints.--json: Output results as JSON.
digest (or tree)
Generates a hierarchical recursive cluster tree of your project's checkpoints (inspired by Spotify's Recursive Embedding and Clustering approach). It groups checkpoints into macro-epics and recursively zooms in to uncover nuanced sub-clusters, complete with an explainability layer that highlights distinguishing keywords, branches, and date ranges.
# View the hierarchical memory tree
bonfire digest
# Or use the alias
bonfire tree
# Limit tree depth
bonfire digest --depth 2
# Output as JSON for external visualization or agent processing
bonfire digest --jsoncreate [message]
Creates a new bonfire checkpoint with rich metadata (Git author, branch, commit SHA, timestamp, and optional tags) stored as standardized YAML frontmatter.
# Create with a direct message
bonfire create "Refactored user authentication logic and added test coverage" -t auth -t refactor
# Pipe from stdin (ideal for multi-line agent summaries and avoids shell quote escaping)
cat summary.md | bonfire create
# or
git diff --stat | bonfire create "Commit overview"
# Read from a file
bonfire create --file ./scratchpad.md -t docsOptions:
-f, --file <path>: Read context message from a text or markdown file.-t, --tag <tags...>: Assign one or more search tags to the checkpoint.-a, --author <name>: Author override (defaults toBONFIRE_AUTHORenvironment variable orgit config user.name).-b, --branch <branch>: Git branch override.
list
Lists existing bonfires in reverse chronological order with formatted metadata (date, author, branch, tags, and summary snippet).
# List recent bonfires (default: 10)
bonfire list
# Show all checkpoints
bonfire list --all
# Show JSON output
bonfire list --jsonread [id]
Displays the contents of a specific bonfire. You can provide the full filename or timestamp ID. If run interactively in a terminal without an ID, it opens an interactive select menu.
bonfire read 2026-09-04T20-36-33prune
Removes older bonfires to keep the directory clean.
# Keep the 5 most recent (default)
bonfire prune
# Keep the last 10
bonfire prune --keep 10
# Preview what would be pruned without deleting
bonfire prune --keep 5 --dry-run
# Remove all checkpoints without interactive confirmation
bonfire prune --all -yinit
Initializes the .bonfire/ directory and creates .bonfire/agent-instructions.md. Also detects agent configuration files and offers to integrate instructions.
# Interactive setup
bonfire init
# Non-interactive / headless setup (auto-configures detected agent files)
bonfire init -ySupported agent configurations:
- Cursor:
.cursorrulesand.cursor/rules/bonfire.mdc - Claude Code:
CLAUDE.md - GitHub Copilot:
.github/copilot-instructions.md - Windsurf / Cascade:
.windsurfrules - Cline / Roo Code:
.clinerules - Gemini CLI:
.gemini/system.md - Open Agent Standard:
AGENTS.md/.agents.md
AI Agent Workflow
Bonfire is designed for seamless, automated use by coding agents without polluting prompt tokens:
┌──────────────────────────────────────────────┐
│ Agent Session Starts │
└──────────────────────┬───────────────────────┘
│
▼
Does the task touch existing features or recent work?
/ \
YES NO
/ \
Run: `bonfire recall "<task>"` Skip or run `bonfire latest --summary`
(Only loads relevant context) (Zero prompt clutter)
\ /
▼ ▼
┌──────────────────────────────────────────────┐
│ Agent Executes Task │
└──────────────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Agent Session Ends │
│ Run: `bonfire create "<summary>"` │
│ - Summarizes progress, state & next steps │
│ - Automatically captures branch & commit │
└──────────────────────────────────────────────┘Checkpoint Format
Checkpoints are stored as Markdown with standard YAML frontmatter in .bonfire/checkpoints/:
---
author: "Niklas"
date: "2026-09-04T20:36:33.195Z"
branch: "feature/auth"
commit: "064252f"
tags:
- auth
- vitest
---
Refactored codebase into modular architecture and added Vitest suite.Legacy format checkpoints (Author: ...\nDate: ...\n---\nMessage) are fully supported and parsed transparently.
Development & Testing
# Install dependencies
npm install
# Run Vitest test suite
npm test
# Build TypeScript to dist/
npm run build