breadcrumb

Breadcrumb

Agents leave notes for other agents.

When an agent fixes a tricky bug or writes code that looks wrong but is intentional, the next agent has no idea. It sees "dead code" and helpfully cleans it up. Or it sees a weird regex and "simplifies" it, breaking a unicode edge case that took hours to debug.

Breadcrumb fixes this. Agents leave notes about files, and future agents see them automatically.

# Agent leaves a note after fixing a tricky bug
breadcrumb add ./src/parser.ts "Regex handles unicode edge cases, don't simplify"

# Future agent reads the file → sees the note automatically
📝 BREADCRUMB: Regex handles unicode edge cases, don't simplify

Installation

npm install -g breadcrumb-cli

Or with other package managers:

pnpm add -g breadcrumb-cli
yarn global add breadcrumb-cli
bun add -g breadcrumb-cli

Quick Start

# Initialize in your repo
breadcrumb init

# Add a note about a file
breadcrumb add ./src/auth.ts "OAuth flow depends on specific token format"

# See notes on a file
breadcrumb check ./src/auth.ts

# List all notes
breadcrumb ls

# Remove a note
breadcrumb rm ./src/auth.ts

Why Not Just Use Comments?

Comments are passive — they sit in a file hoping to be noticed. Breadcrumbs are injected directly into the agent's context the moment it reads the file. They can't be skimmed over or missed.

Also:

• Comments aren't discoverable — breadcrumb ls shows all notes in a repo
• Comments can't span files — One breadcrumb can cover an entire directory

When to Leave Notes

• Code that looks like it could be simplified but shouldn't be
• Bug fixes for edge cases that aren't obvious
• Intentional workarounds
• Security-critical patterns (SQL injection prevention, etc.)
• Performance tuning that looks "overengineered"

Example: Protecting Critical Code

# Money calculations - integers avoid floating point errors
breadcrumb add ./src/utils/money.js "All money as integers (cents) to avoid floating point errors. Ceiling for tax is legally required."

# API retry logic tuned for rate limiting
breadcrumb add ./src/api/client.js "Retry delays tuned for rate limiting - 100ms/500ms/2s/5s matches API provider's backoff recommendations"

# SQL injection prevention
breadcrumb add ./src/db/query.js "CRITICAL: Parameterized queries prevent SQL injection. Never use string interpolation for values."

Now when an agent tries to "simplify" this code:

Request	Agent Response
"Use floating point for money"	❌ Refuses - cites precision errors
"Simplify retry to fixed 1s delay"	⚠️ Warns about rate limit tuning
"Use template literals for SQL"	❌ Hard refuses - SQL injection risk
"Do a full code review and simplify"	✅ Reports all code is intentionally designed

Commands

Command	Description
init	Create .breadcrumbs.json in current repo
add <path> <message>	Add a note (warns about overlaps)
edit <path-or-id>	Edit a note in place
rm <path>	Remove a note
check <path>	See notes on a file
search <query>	Find notes by content
coverage [path]	Show breadcrumb coverage stats
verify [path]	Check if notes are still valid
ls	List all notes
status	Quick overview (counts)
prune	Remove expired notes

Add Options

breadcrumb add <path> <message> [options]
  -s, --severity <level>   # info (default) or warn
  -l, --line <range>       # Anchor to line (42) or range (42-50)
  -e, --expires <date>     # Expiration date (ISO 8601)
  --ttl <duration>         # Time-to-live (30s, 5m, 2h, 7d)
  --evidence-input <str>   # Test input that would break if changed
  --evidence-expected <str> # Expected behavior
  --evidence-actual <str>  # What happens if code is changed (optional)
  --no-overlap-check       # Skip overlap detection

Edit Options