threadlinking CLAUDE.md

Threadlinking

Git tracks what changed. Threadlinking tracks why.

A local-first tool for preserving decision-making context alongside the files you create. When you return to code weeks later, threadlinking tells you the reasoning behind it.

---

Session Protocol

Starting a Session

1. Check existing threads: threadlinking list
2. If resuming work: Note the relevant thread name for this session
3. For unfamiliar code: Use threadlinking explain path/to/file before modifying

During a Session

• Before modifying significant files: threadlinking explain path/to/file
• When making decisions: threadlinking snippet THREAD "why we chose X over Y"
• When creating files: threadlinking attach THREAD path/to/file
• Finding related context: threadlinking semantic-search "what you're looking for"

Ending a Session

For significant work sessions, offer to capture what was accomplished:

• Summarize key decisions made
• Save snippets for important reasoning
• Attach any new files to the appropriate thread

---

Thread Detection

Proactively detect when context should be saved. Look for:

• User mentions a project name ("working on myproject")
• Significant new work spanning multiple files
• Architectural decisions ("let's use PostgreSQL because...")
• User asks to "remember this" or "save this context"
• Design choices that future sessions should know about
• Trade-off discussions ("we could do X or Y, let's go with X because...")

When detected, prompt:

"This looks like context worth preserving. Should I save it to a thread?
I'd suggest 'myproject' - or name it something else."

If a thread might exist: Check threadlinking list first, then ask:

"Should this be part of the existing 'myproject' thread?"

Remember the thread for the session. Once confirmed, use it for all context saves without asking again.

---

What to Save

Good Snippets (Save These)

• Decisions: "Chose JWT over sessions for stateless API scaling"
• Trade-offs: "Picked PostgreSQL over MongoDB - need ACID for payments"
• Constraints: "Must support offline mode, so local-first architecture"
• Pivots: "Switched from REST to GraphQL after N+1 query issues"
• Architecture: "Event sourcing pattern for audit trail requirements"