subagent-reuse

MCP server for Claude Code that stops subagents from wasting tokens on work that's already been done.

The Problem

Claude Code spawns subagents — Plan agents to research, Explore agents to search, general agents to implement. Each one starts from zero. It reads files, builds understanding, does the work.

Then the next subagent comes along for a related task. It reads the same files. Rebuilds the same understanding. Burns the same tokens.

Across a single session, this adds up. Across multiple sessions, it compounds. A planning agent reads 7 files, an implementation agent re-reads all 7, a follow-up bug fix agent re-reads them again. That's 21 file reads for context that could have been carried over.

What This Does

Sits between Claude Code and its subagents. Before a new agent is spawned, route_task checks if an existing agent already has the relevant files loaded.

You: "Fix the auth redirect bug"
→ route_task(task, files=["src/auth/callback.ts", "src/middleware/session.ts"])
→ CREATE_NEW (no agent knows these files)
→ Agent spawns, reads files, fixes the bug

You: "Now add refresh token rotation"
→ route_task(task, files=["src/auth/callback.ts", "src/auth/tokens.ts"])
→ REUSE (previous agent already read callback.ts)
→ Agent resumes with existing context — no re-reading

If a file changed since the agent last read it, you get a staleness warning:

{
  "action": "REUSE",
  "stale_files": ["src/auth/callback.ts"],
  "stale_warning": "Re-read callback.ts — it changed since this agent last read it."
}

When no strong match exists, the response includes summaries of existing agents so Claude can decide for itself whether any are relevant — no word matching, no NLP. The LLM is better at semantic judgment than any scoring algorithm.

Install

npx subagent-reuse --setup

One command. This adds the MCP to Claude Code and auto-approves all tool permissions so you're never prompted. The server auto-detects your project from the working directory.

If you prefer to do it manually:

claude mcp add subagent-reuse -- npx subagent-reuse

How It Works

Auto-Discovery

Scans Claude Code's native session storage (~/.claude/projects/) for the current project. Extracts from each subagent's JSONL transcript:

• Files read — from Read tool calls
• Files modified — from Edit/Write tool calls
• Learnings — from assistant text blocks
• Compact summaries — from Claude Code's built-in summarization

No manual logging. No parallel storage system. It reads what Claude Code already writes.

Staleness Detection

Each agent's known files are tracked with SHA-256 content hashes (Merkle tree). At routing time:

• Root hash comparison — instant check if anything changed
• If changed, leaf comparison — pinpoints exactly which files are stale
• Stale files get half score weight in routing
• Stale modifications get zero bonus

Routing

Purely structural signals — no text matching:

| Signal | Points | Notes | |---|---|---| | File overlap | 0-50 | Stale files get 50% weight | | Modified bonus | 0-15 | Stale modifications get 0 | | Directory match | 0-20 | Exact, parent/child, or shared ancestor | | Recency | 0-10 | How recently the agent was active |

Score >= 40 → REUSE (with staleness warnings if applicable) Score < 40 → CREATE_NEW (with existing agent summaries for LLM review)

Tools

| Tool | Purpose | |---|---| | route_task | Check for existing agents before spawning. Only call when the task is complex enough to warrant a subagent. | | get_context | Load an agent's full context — files, learnings, staleness report. | | recall | Search prior work across all agents. Use to pull relevant knowledge into a new agent. | | list_agents | See all discovered agents for the current project. | | register_agent | Manually register an agent (for hybrid use alongside auto-discovery). | | log_work | Add annotations to an agent's context beyond what auto-scanning extracts. | | mark_done | Exclude an agent from future routing. Its learnings remain searchable via recall. |

Add to CLAUDE.md

For best results, add this to your project's CLAUDE.md so Claude follows the workflow automatically:

# Subagent Reuse Protocol

## Rule
Only spawn subagents for complex, multi-step tasks (deep exploration, large refactors, parallel workstreams). For simple tasks, handle them directly.

When you DO decide to spawn a subagent, call `route_task` first. Always.

## Workflow
route_task(task, files?, directory?)
- REUSE → call get_context(agent_id), check stale_files, re-read any that changed
- CREATE_NEW → spawn a new agent. Check existing_agents in response — if one looks relevant, use get_context instead

Environment Variables

All optional. Defaults work out of the box.

| Variable | Default | Purpose | |---|---|---| | CLAUDE_PROJECT_PATH | process.cwd() | Override project path detection | | CLAUDE_PROJECTS_DIR | ~/.claude/projects/ | Override Claude Code's storage dir | | SUBAGENT_DATA_DIR | ~/.subagent-reuse/ | Where index and Merkle trees persist | | SUBAGENT_SCAN_INTERVAL_MS | 30000 | Re-scan cooldown in ms |

License

MIT