Skip to content

thrialectics/threadlinking

BranchesTags

Repository files navigation

Threadlinking

Git tracks what changed. Threadlinking tracks why.

You built something three weeks ago. Now you're staring at it, trying to remember why you made that choice. The commit message says "add auth module" -- but why JWT? Why not sessions? What constraint drove that decision?

Threadlinking captures decision rationale alongside your code. It works natively with Claude Code -- Claude detects decisions as you make them, saves the reasoning, and surfaces it when you (or a teammate) come back later.

A thread is a container for an idea or project, not a task. One thread spans months of work, dozens of files, and hundreds of context snippets. When you start a new session weeks later, threadlinking connects it back to the earlier decisions.

Claude Code Plugin

Threadlinking ships as a Claude Code plugin — when you run threadlinking init, it installs an MCP server that gives Claude direct access to threadlinking tools. Claude can create threads, save snippets, link files, and search context without you ever touching the CLI.

For slash commands and skills, also install the plugin inside Claude Code:

/plugin marketplace add thrialectics/threadlinking
/plugin install threadlinking

MCP Tools

Threadlinking exposes 14 tools to Claude Code via MCP:

Tool Description
threadlinking_snippet Add a context snippet to a thread (auto-creates thread if needed)
threadlinking_create Create a new empty thread
threadlinking_delete Permanently delete a thread and its snippets
threadlinking_attach Link a file to a thread
threadlinking_detach Remove a file link from a thread
threadlinking_explain Show why a file exists — the decisions and reasoning behind it
threadlinking_show View full thread details including all snippets and linked files
threadlinking_list List all threads and pending unlinked files
threadlinking_search Search threads by keyword
threadlinking_semantic_search Search threads by semantic similarity
threadlinking_analytics Get usage analytics and insights
threadlinking_export Export thread(s) in markdown, JSON, or timeline format
threadlinking_reindex Rebuild the semantic search index
threadlinking_status Check available features and index status

Slash Commands

The plugin adds slash commands you can use directly in Claude Code:

Command What it does
/threadlink <thread> "context" [file] Save context and optionally attach a file
/context [thread] List all threads, or show details of one
/explain <file> Show why a file exists
/thread-review [thread] Review full history of a thread

The plugin also ships a threadlinking skill that teaches Claude the capture protocol — when to save decisions, what makes a good snippet, and how to use the MCP tools.

Hooks

Two Claude Code hooks automate context tracking:

  • PostToolUse — When Claude creates or edits a file, the hook automatically adds it to the pending files list so nothing slips through untracked.
  • SessionStart — At the start of every session, shows your active threads and any pending unlinked files, so Claude (and you) have immediate context.

CLAUDE.md Integration

The init also appends instructions to your global ~/.claude/CLAUDE.md that teach Claude when and how to save context — detecting decisions, prompting for thread names, and saving snippets at natural points in the conversation.

Claude Desktop

The MCP server also works with Claude Desktop. Add it to your config manually:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "threadlinking": {
      "command": "threadlinking-mcp"
    }
  }
}

Installation

Quick Start

Install globally and run the guided setup:

npm install -g threadlinking
threadlinking init

The global install is required because Threadlinking's hooks need threadlinking available as a command between sessions. The setup walks you through everything:

Setting up threadlinking...

Checking environment...
  ✓ Claude Code detected
  ✓ ~/.claude directory exists

[1/5] PostToolUse hook (auto-tracks files you create)
      Status: Not installed
      Install to ~/.claude/settings.json? (Y/n) y
      ✓ Hook installed

[2/5] SessionStart hook (shows context at session start)
      Status: Not installed
      Install to ~/.claude/settings.json? (Y/n) y
      ✓ Hook installed

[3/5] MCP Server (gives Claude direct access to threadlinking tools)
      Status: Not configured
      Add to ~/.claude/mcp.json? (Y/n) y
      ✓ MCP server configured

[4/5] CLAUDE.md instructions (teaches Claude when/how to use threadlinking)
      Status: Not present
      Append to ~/.claude/CLAUDE.md? (Y/n) y
      ✓ Instructions added

[5/5] Ignore file (filters noise from pending files list)
      Status: Not present
      Create ~/.threadlinkingignore? (Y/n) y
      ✓ Ignore file created

Done! Threadlinking is fully configured.

Start a new Claude Code session to begin.
Tip: Run `threadlinking list` to see your threads.

Check your setup anytime:

threadlinking init --status

Non-interactive install (scripts/CI):

threadlinking init --no-interactive

Standalone CLI (No AI Integration)

Threadlinking also works as a standalone CLI tool without any Claude/AI integration. If you just want to manually track context for your projects, skip the init and use it directly:

# Create a thread and add context
threadlinking snippet myproject "Starting auth module with JWT"

# Link files to threads
threadlinking attach myproject src/auth/jwt.ts

# Later, check why a file exists
threadlinking explain src/auth/jwt.ts

# See all your threads
threadlinking list

See Commands for the full reference.

Manual Setup

If you prefer to configure components individually instead of using init:

MCP Server only (add to ~/.claude/mcp.json):

{
  "mcpServers": {
    "threadlinking": {
      "command": "threadlinking-mcp"
    }
  }
}

For Claude Desktop, see Claude Desktop above.

What Gets Installed

Component Purpose Location
PostToolUse hook Auto-tracks files you create/edit ~/.claude/settings.json
SessionStart hook Shows thread context at session start ~/.claude/settings.json
MCP Server Gives Claude direct tool access ~/.claude/mcp.json
CLAUDE.md block Teaches Claude when/how to use threadlinking ~/.claude/CLAUDE.md
Ignore file Filters noise from pending files ~/.threadlinkingignore

All components are optional and can be skipped during init.

How It Works

Claude automatically detects when decisions are being made and prompts you:

You: "Let's build a new authentication system using JWT"
Claude: "This looks like a decision worth preserving. Should I create
        a thread for this? I'd suggest 'myproject' - or name it something else."
You: "Call it auth_system"
Claude: [remembers: current thread = auth_system]
Claude: [creates src/auth/jwt.ts]
Claude: [runs] threadlinking snippet auth_system "Building JWT auth for stateless API"
Claude: [runs] threadlinking attach auth_system src/auth/jwt.ts

Once you confirm a thread, Claude uses it automatically for the rest of the session.

Later, when anyone revisits the code (maybe weeks later, in a new session):

You: "Why did we build auth this way?"
Claude: [runs] threadlinking explain src/auth/jwt.ts
Claude: "You chose JWT over sessions because you wanted a stateless API..."

Automatic Thread Detection

Claude looks for signals that decisions are being made:

  • Project mentions: "We're working on myproject" or "This is for client X"
  • Architectural choices: Creating files that represent design decisions
  • Trade-off discussions: Choosing between approaches (REST vs GraphQL, etc.)
  • Explicit requests: "Remember this" or "Save this context"

When Claude detects these signals, it prompts you to create or use a thread. You stay in control — Claude asks, you confirm.

Cross-Session Context

Threads persist across sessions and teammates. One thread accumulates decision context over the life of a project:

# Week 1: Starting the project
threadlinking snippet myproject "Building a SaaS for X. Starting with auth."
threadlinking attach myproject src/auth/jwt.ts

# Week 3: New session, same thread
threadlinking snippet myproject "Added API layer. REST for simplicity."
threadlinking attach myproject src/api/routes.ts

# Month 2: Still the same thread
threadlinking snippet myproject "Pivoted to cursor pagination after scale issues"
threadlinking attach myproject src/api/pagination.ts

One thread, many sessions, complete decision history. Works across repos too — the thread lives in ~/.threadlinking/, not in your project.

Working with Thread Names

Thread names should be project or idea level, not task level. Think myproject or saas_thing, not auth_v2 or fix_bug_123.

Set the Current Thread

Tell Claude what you're working on at the start of a session:

You: "We're working on myproject today"
Claude: [remembers: current thread = myproject]
Claude: [automatically uses myproject for all context saves]

This works automatically with the global CLAUDE.md setup from Quick Start.

Claude Proposes, User Confirms

Let Claude suggest names based on the work:

Claude: "I'll save this context. Thread name: saas_analytics?"
You: "Sure" / "Call it myproject instead"

Discovery First

Don't remember the name? Ask:

You: "What threads do I have?"
Claude: [runs] threadlinking list
Claude: "You have: myproject, research_llm, client_acme..."
You: "This is part of myproject"

User Names Explicitly

Take control of the mental model upfront:

You: "This project is called 'myproject' - save context as we go"
Claude: [uses myproject for the session]

Manual Usage

You can also use threadlinking directly:

# Save context
threadlinking snippet myproject "Decided on REST for simpler caching"
threadlinking attach myproject src/api/routes.ts

# Find context
threadlinking explain src/api/routes.ts
threadlinking show myproject
threadlinking search "caching"

Commands

Core Commands

Command Description
init Guided setup for hooks, MCP server, CLAUDE.md
init --status Check what's configured without changes
list List threads + untracked files
snippet THREAD "text" Add context (auto-creates thread)
snippet THREAD "text" --tags a,b Add context with tags
attach THREAD file Link file to thread
explain file Show why this file exists
show THREAD View thread with all snippets
show THREAD --tag decision Filter snippets by tag
search "query" Keyword search across threads
detach THREAD file Unlink file from thread
rename OLD NEW Rename a thread
delete THREAD Delete a thread and its snippets
audit Check for broken links, orphans, stale threads
audit --fix Preview removing dead file links (dry run)
audit --fix --confirm Remove dead file links
prune Drop pending files matched by .threadlinkingignore
list --clear-pending Clear untracked files list

Semantic Search

Search your threads by meaning, not just keywords:

# Build the semantic index (run once, then after adding many snippets)
threadlinking reindex

# Search by natural language
threadlinking semantic-search "authentication decisions"
threadlinking semantic-search "why did we choose this database"

How it works:

  • Uses all-MiniLM-L6-v2 embeddings
  • Runs entirely locally via @xenova/transformers (no API calls)
  • First run downloads the model (~30MB, cached at ~/.cache/huggingface)
  • Index stored at ~/.threadlinking/semantic-index/

Analytics & Export

Analytics and export are available as MCP tools — ask Claude for usage stats (threadlinking_analytics) or to export threads as markdown, JSON, or a timeline (threadlinking_export). They are not CLI commands.

Data Storage

Everything is stored locally at ~/.threadlinking/. No cloud, no sync — just JSON files your team controls.

  • index.json — thread metadata (names, summaries, file counts)
  • threads/*.json — one file per thread with snippets and linked files
  • semantic-index/ — local embeddings for semantic search
  • pending.json — files edited but not yet linked

Security

Roadmap

See ROADMAP.md for upcoming features and ideas.

License

MIT

Built by Marianne

About

threadlinking.netlify.app/

Resources

Readme

License

MIT license
Activity

Stars

22 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

v3.1.0 Latest
Mar 9, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages