Breadcrumb

Leave notes on files that persist across agent sessions.

When to use

After making changes that future agents might misunderstand:

• Non-obvious code that looks like it could be simplified
• Bug fixes for edge cases
• Intentional workarounds
• Security-critical patterns
• Performance tuning

Core workflow

1. Before editing, check for warnings:

breadcrumb check ./src/api/users.ts

• Exit 0 = safe to proceed (clear/info)
• Exit 1 = warning exists, read the suggestion field

2. After non-obvious changes, leave a note:

breadcrumb add ./src/api/users.ts "Retry logic tuned for rate limits"

Command reference

| Command | Purpose | |---------|---------| | breadcrumb check <path> | Check path for notes (-r for recursive) | | breadcrumb add <path> <message> | Leave a note (-s severity, --ttl expiration) | | breadcrumb edit <path-or-id> | Edit a note (-m message, -a append, -s severity) | | breadcrumb verify [path] | Check if notes are stale (--update to refresh hashes) | | breadcrumb search <query> | Find notes by content (-r for regex) | | breadcrumb coverage [path] | Show breadcrumb coverage stats | | breadcrumb ls | List all notes (-s filter by severity) | | breadcrumb status | Quick overview (counts) | | breadcrumb rm <path> | Remove a note (-i by ID) | | breadcrumb prune | Remove expired notes |

Staleness detection

Notes track file content hashes. When you see [STALE] prefix:

• The file has changed since the note was written
• The note may no longer be accurate
• Use judgment: the warning might still apply, or might be outdated

📝 BREADCRUMB: [STALE] Don't simplify this regex
                ↑ Code changed - verify note still applies

After reviewing stale notes, update hashes with:

breadcrumb verify --update

Output format

All commands output JSON. Key fields:

• status: "clear", "info", or "warn"
• suggestion: Actionable guidance when warnings exist
• breadcrumbs: Array of matching breadcrumb objects
• staleness: "verified", "stale", or "unknown" (per breadcrumb)