Write breadcrumbs (during/end of session):

After completing significant work
After hitting a dead end or failed approach
Before ending a session
User says "remember this" or "note for next time"
After discovering something important about the codebase

Instructions

File Location

.claude/breadcrumbs.md    # Project-specific (preferred)
~/.claude/breadcrumbs/    # Global breadcrumbs by project

Create .claude/ directory if it doesn't exist. Add to .gitignore if user prefers.

Reading Breadcrumbs (Session Start)

<read_breadcrumbs> At session start, check for breadcrumbs:

cat .claude/breadcrumbs.md 2>/dev/null || echo "No breadcrumbs found"

If found, summarize key points:

## Previous Session Context

**Last worked on:** [topic]
**Status:** [completed/in-progress/blocked]
**Key notes:**
- [important finding 1]
- [important finding 2]

**Warnings from past self:**
- [thing that didn't work]

Don't read the whole file aloud - summarize what's relevant. </read_breadcrumbs>

Writing Breadcrumbs

<write_breadcrumbs> Append to breadcrumbs file (don't overwrite):

---
## [Date] - [Brief Topic]

**What we worked on:**
[1-2 sentence summary]

**What worked:**
- [approach that succeeded]

**What didn't work:**
- [approach that failed] - [why it failed]

**Left off at:**
[current state, what's next]

**Notes for next time:**
- [important context]
- [gotcha to remember]
- [file locations worth knowing]

</write_breadcrumbs>

Breadcrumb Types

Discovery breadcrumb - Found something important:

## 2024-01-15 - Discovery: Auth flow

**Found:** Auth doesn't use middleware. It's in route handlers.
**Location:** src/routes/api/*.ts - each route calls `validateSession()` directly
**Why it matters:** Don't look in middleware/ for auth stuff

Dead end breadcrumb - Tried something that failed:

## 2024-01-15 - Dead End: Redis caching

**Tried:** Adding Redis cache for user sessions
**Failed because:** App uses serverless, Redis connections don't persist
**Don't try again:** Any persistent connection solution
**Instead:** Use edge-compatible cache (KV store)

Progress breadcrumb - Work in progress:

## 2024-01-15 - In Progress: API refactor

**Done:**
- [x] Moved routes to /api/v2
- [x] Updated auth middleware

**Not done:**
- [ ] Update client SDK
- [ ] Migration script

**Blocked on:** Waiting for DB schema approval
**Next steps:** Once approved, run migration then update SDK

Context breadcrumb - Important background:

## 2024-01-15 - Context: Why we use X

**Decision:** Using Prisma instead of raw SQL
**Why:** Team preference, type safety, migration tooling
**Trade-off:** Slower queries but faster development
**Don't suggest:** Switching to raw SQL (already discussed)

Breadcrumb Hygiene

Pruning old breadcrumbs:

Keep last 10-15 entries
Archive old ones to .claude/breadcrumbs-archive.md
Delete truly obsolete info (completed features, resolved issues)

When to prune:

File exceeds ~200 lines
User asks to clean up
Old breadcrumbs reference deleted code

Output Format

When reading:

📍 **Breadcrumbs found** - Last session: [date]

[Brief summary of relevant context]

Ready to continue, or starting fresh?

When writing:

📝 **Breadcrumb dropped**

[What was recorded]

This will be here next session.

NEVER

Overwrite the entire breadcrumbs file (append only)
Include sensitive data (passwords, keys, secrets)
Write breadcrumbs for trivial work
Ignore existing breadcrumbs at session start
Write vague notes ("worked on stuff")

ALWAYS

Check for breadcrumbs at session start
Record dead ends (future you will thank you)
Include file paths for important discoveries
Note the "why" not just the "what"
Keep entries scannable (bullets, not paragraphs)

Example Session

Session 1 ends:

---
## 2024-01-15 - Auth Bug Investigation

**What we worked on:**
Users randomly getting logged out. Investigated session handling.

**What we found:**
- Sessions stored in Redis with 1hr TTL
- TTL not refreshing on activity (bug in middleware)
- File: src/middleware/session.ts:45 - missing `touch()` call

**What didn't work:**
- Checked JWT expiry first - red herring, JWTs are fine
- Looked in auth/ directory - session logic isn't there

**Left off at:**
Found the bug, haven't fixed yet. Fix is adding `session.touch()` after validation.

**Notes for next time:**
- Session middleware is in src/middleware/session.ts, NOT src/auth/
- Redis TTL is 1hr (REDIS_SESSION_TTL env var)

Session 2 starts:

📍 Breadcrumbs found - Last session: 2024-01-15

Previous session investigated logout bug:
- Found: session TTL not refreshing (src/middleware/session.ts:45)
- Fix identified: add session.touch() call
- Note: session code is in middleware/, not auth/

Ready to apply the fix?

breadcrumbs

Breadcrumbs

When To Activate