npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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-cli

Or 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" --json

Options:

  • -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 --json

create [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 docs

Options:

  • -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 to BONFIRE_AUTHOR environment variable or git 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 --json

read [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-33

prune

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 -y

init

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 -y

Supported agent configurations:

  • Cursor: .cursorrules and .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