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

breadcrumb edit <path-or-id> [options]
  -m, --message <text>     # Replace message
  -a, --append <text>      # Append to message
  -s, --severity <level>   # Change severity
  -l, --line <range>       # Update line anchor
  -e, --expires <date>     # Set expiration
  --ttl <duration>         # Set TTL
  --evidence-input <str>   # Update evidence input
  --evidence-expected <str> # Update evidence expected
  --evidence-actual <str>  # Update evidence actual
  --clear-expiration       # Remove expiration
  --clear-line             # Remove line anchor
  --clear-evidence         # Remove evidence

Search Options

breadcrumb search <query> [options]
  -r, --regex              # Treat query as regex
  -c, --case-sensitive     # Case-sensitive literal search
  -i, --ignore-case        # Case-insensitive regex search
  -p, --path <segment>     # Filter by path segment
  -s, --severity <level>   # Filter by severity

Coverage Options

breadcrumb coverage [path] [options]
  -g, --glob <pattern>     # File pattern (default: **/*)
  --show-covered           # List covered files
  --show-uncovered         # List uncovered files
  -l, --limit <n>          # Max files to list (default: 20)

Check Options

breadcrumb check <path> [options]
  -r, --recursive          # Check all files in directory
  -c, --concise            # Token-efficient output for agents
  --verify                 # Update hashes after checking

List Options

breadcrumb ls [options]
  --summary                # Return only counts (total, warnings, info)

Verify Options

breadcrumb verify [path] [options]
  --update                 # Update hashes after verification
  --stale-only             # Only show stale breadcrumbs

Staleness Detection

Notes can become outdated when the code they protect changes. Breadcrumb tracks file content hashes to detect when notes may no longer be valid.

# Check if any notes are stale
breadcrumb verify

# Output shows staleness status:
# - verified: File unchanged since note was added
# - stale: File has changed, note may need review
# - unknown: No hash stored (older notes or directory/glob patterns)

# Update hashes after reviewing stale notes
breadcrumb verify --update

When you add a note to a specific file, its content hash is automatically captured:

breadcrumb add ./src/api/client.ts "Retry delays tuned for rate limits"
# Hash is stored → future changes detected

The check command also shows staleness for each note, helping agents understand which notes are trustworthy.

Line Anchoring

Anchor notes to specific lines when the warning applies to a particular section:

# Single line
breadcrumb add ./src/parser.ts "Lookbehind handles escapes" -l 142

# Line range
breadcrumb add ./src/auth.ts "Timing-safe comparison" -l 67-72

Output shows the anchored lines:

{
  "status": "info",
  "suggestion": "Timing-safe comparison (lines 67-72)"
}

Evidence

Attach proof to notes — the input that would break if the code changed:

breadcrumb add ./src/parser.ts "Regex handles escaped templates" \
  --evidence-input '\${foo}' \
  --evidence-expected 'should NOT match' \
  --evidence-actual 'would match if simplified'

Evidence answers "what breaks?" — agents can verify whether their change triggers the failure case:

{
  "status": "info",
  "suggestion": "Regex handles escaped templates\nEvidence:\n  Input: \\${foo}\n  Expected: should NOT match\n  If changed: would match if simplified"
}

Concise Mode

For agents with limited context, use -c for token-efficient output:

breadcrumb check ./src/file.ts -c

Before (~150 tokens): Full metadata with id, hash, timestamps, added_by... After (~40 tokens): Just status and suggestion.

Claude Code Plugin

For Claude Code users, the plugin auto-shows notes when reading files:

/plugin marketplace add tylergibbs1/breadcrumb
/plugin install breadcrumb@breadcrumb-marketplace

The plugin:

• Auto-installs the CLI if not present
• Auto-initializes .breadcrumbs.json on session start
• Injects notes into Claude's context when reading files
• Claude acknowledges notes when they conflict with the current task

Vendor Agnostic

Breadcrumb works with any AI agent system that can run shell commands.

Component	Requirement
CLI (breadcrumb)	Node.js 18+ (or Bun)
.breadcrumbs.json	Plain JSON - works everywhere
Claude Code plugin	Optional integration

For other tools (Cursor, Windsurf, Aider), add to your system prompt or equivalent:

• Check for notes before editing: breadcrumb check <file>
• Leave notes after non-obvious changes: breadcrumb add <file> "message"

Storage

Notes are stored in .breadcrumbs.json at repo root:

{
  "version": 2,
  "breadcrumbs": [
    {
      "id": "b_1a2b3c",
      "path": "src/utils/money.js",
      "pattern_type": "exact",
      "message": "All money as integers (cents) to avoid floating point errors",
      "severity": "info",
      "added_by": { "agent_id": "agent" },
      "added_at": "2026-01-10T14:30:00Z"
    }
  ]
}

License

MIT