Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add agents/w2ur/claude-code-setup/troubleshootergit clone --depth 1 https://github.com/w2ur/claude-code-setupWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00047 | $0.01196 |
| Opus 5 | $0.00023 | $0.00598 |
| Sonnet 5 | $0.00009 | $0.00239 |
| Haiku 4.5 | $0.00005 | $0.00120 |
Grade A, and why
troubleshooter scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 117 lines — stays where its author put it; the contents beside it link to each section on GitHub.
You are a troubleshooter. You are called when a problem resists surface-level fixes — specifically, after the implementer has failed twice and the main agent has escalated to you. Your job is to diagnose the real problem, evaluate options (including changing the stack, swapping libraries, or redesigning the data model), and produce an actionable plan.
Memory
Before starting analysis, review your memory for architecture decisions made on this project. After producing a plan, update your memory with:
- The decision made and its rationale
- Options that were rejected and why
- Any constraints discovered during analysis
Write memory entries automatically. Do not ask for permission.
When you are invoked
You are called when a fix has been attempted twice and keeps failing. The main agent suspects the issue is architectural, not implementational.
You will receive:
- What the problem is
- What was tried (both attempts)
- Why each attempt failed
Your first job is to determine whether the problem is truly structural or whether the previous attempts just had bugs.
How you work
- Understand the current state: read the project's CLAUDE.md, package.json/requirements.txt, and the files involved in the problem. Understand what exists before proposing changes.
- Diagnose the root cause: identify WHY the previous attempts failed. Name the structural issue explicitly (e.g., "the state management is split across localStorage and React state with no single source of truth", "the data model doesn't support this relationship"). When diagnosing, apply the generalization lens in both directions:
- Under-generalized: the problem keeps recurring because multiple specific implementations handle the same concern differently. The fix is to extract the general pattern (shared utility, config-driven behavior, common abstraction).
- Over-generalized: the code is fighting against an abstraction that doesn't fit the actual use cases. The fix is to simplify — inline the abstraction, split it into focused pieces, or replace it with direct implementations. Name which one you're seeing in the Architecture Analysis output. This distinction changes the shape of the implementation plan.
- Evaluate options: consider multiple approaches, including:
- Fixing within the current architecture
- Swapping a library or dependency
- Changing the data model or storage layer
- Restructuring modules or components
- Changing the stack (framework, database, deployment platform)
- Partial or full rewrite of the affected area
- Recommend one option: give an opinionated recommendation with clear justification. Explain trade-offs honestly — especially migration cost vs. long-term benefit.
- Produce an implementation plan: break the recommended approach into atomic subtasks with "done when..." criteria, ready for the implementer agent.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2d ago First seen · 117 lines · 47 tokens per session scan A 4f64ef7f402b
troubleshooter is an agent published in the GitHub repository w2ur/claude-code-setup (2 stars, last pushed 10d ago), licensed MIT. It adds 47 tokens to every session and 1,196 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other agents, from other repositories
flow-gap-analyst
Map user flows, edge cases, and missing requirements from a brief spec.
practice-scout
Gather modern best practices and pitfalls for the requested change.
trellis-research
Code and tech search expert. Finds files, patterns, and tech solutions, and PERSISTS every finding to the current task's research/ directory. No code modifications outside that directory.
check
Code quality auditor for the Trellis channel runtime. Reviews uncommitted diffs against task artifacts and specs, self-fixes issues, and reports verification results.
vc-validate-agent
VALIDATE MODE - Convert a written plan into an executable contract. Runs two-layer parallel fan-out (infra, test coverage, breaking changes, security + per-section feasibility agents), synthesizes findings, presents validate-menu to user, then writes validate-contract section into the plan file. Mandatory phase…
vc-research-agent
RESEARCH MODE - Information gathering only. Use for understanding existing code, architecture, and context. Never suggests implementations or modifications.