Claude Code Sub-Agent Collective
Installs 30+ TDD-enforcing sub-agents for Claude Code, coordinated through a central routing hub and context engineering for faster prototyping.
- Source repo
- vanzan01/claude-code-sub-agent-collective
- Stars
- ★ 526
- Last updated
- 7mo ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 56/100 · Major gaps
At a glance
- Works with
- Platform-specificClaude Code
- You'll need
- Typical use
- Solo developers building MVPs who want every feature to ship with tests written first
- Main limitation
- Experimental by the author's own admission — some agents are still rough and the research phase can be slow
- Maintenance
- No commits for 6+ monthslast commit 2026-04-20
- Source review
- 56/100 · Major gaps
What does this agent do, and when should you use it?
This is an experimental personal project by vanzan01 that installs a collective of AI sub-agents into Claude Code projects via the npm package claude-code-collective. Installation generates a CLAUDE.md behavioral rule file, 30+ agent definitions under .claude/agents/, TDD enforcement hooks in .claude/hooks/, and a Vitest test setup under .claude-collective/. Its hub-and-spoke architecture routes requests through the /van command to @task-orchestrator, which analyzes complexity and delegates to implementation, testing, quality, and devops specialist agents. Every implementation agent follows a RED → GREEN → REFACTOR TDD contract and pulls real library documentation via Context7 instead of guessing APIs. The author explicitly frames it as an opinionated experimental tool for rapid MVP development, not production-ready enterprise software.
Running npx claude-code-collective init writes CLAUDE.md behavioral rules, a settings.json hook configuration, 30+ agent definition files (such as prd-research-agent.md and task-orchestrator.md), the lib/research-analyzer.js complexity analysis engine, and hook scripts like test-driven-handoff.sh and collective-metrics.sh. At runtime, the /van command hands requests to @task-orchestrator, which uses ResearchDrivenAnalyzer to score complexity and parallelize work across specialists like @component-implementation-agent, @feature-implementation-agent, and @testing-implementation-agent. Agents first query Context7 for real documentation, then write tests (RED), implement minimal code to pass them (GREEN), refactor (REFACTOR), and emit a standardized DELIVERY COMPLETE report including test results. @functional-testing-agent performs browser testing with Playwright, while @quality-agent, @enhanced-quality-gate, and @completion-gate block completion until standards are met. The status, validate, repair, and clean subcommands manage the installation lifecycle.
- Solo developers building MVPs who want every feature to ship with tests written first
- Claude Code users tired of manually looking up library docs who want agents reading real documentation via Context7
- Teams needing complex features broken down and dispatched in parallel to specialist agents
- Projects that want hook-based, mechanical enforcement of TDD so agents cannot skip tests
- Workflows requiring Playwright browser-level functional testing of UI components like React
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npx claude-code-collective initnpx claude-code-collective init --minimalnpx claude-code-collective init --testing-onlynpx claude-code-collective init --hooks-only
- Runtime
- Node.js 16.0.0+
How do you install or deploy this agent?
Requires Node.js >= 16.0.0, NPM >= 8.0.0, and Claude Code with MCP and hook support.
npx claude-code-collective initOptional selective installs:
npx claude-code-collective init --minimal
npx claude-code-collective init --testing-only
npx claude-code-collective init --hooks-only
npx claude-code-collective init --interactiveYou must restart Claude Code after installation for hooks to load.
How do you use this agent?
In Claude Code, invoke /van to start the flow, e.g. "Build a simple todo app with React". Expected flow: routed to research → task breakdown → tests written first → implementation. Day-to-day management commands:
npx claude-code-collective status
npx claude-code-collective validate
npx claude-code-collective repair
npx claude-code-collective cleanIf installation fails, check node --version, clear the npm cache, or retry with --force.
What are this agent's strengths and limitations?
- Hook system mechanically enforces test-first development before any code is written
- Context7 integration makes agents use real, current library documentation instead of inventing APIs
- Hub-and-spoke routing through @task-orchestrator prevents agents from self-selecting the wrong approach or descending into peer-to-peer chaos
- Complete installation lifecycle commands: validate, repair, and clean
- Experimental by the author's own admission — some agents are still rough and the research phase can be slow
- Tightly coupled to Claude Code's hook and MCP mechanisms; Claude Code must be restarted after install
- Strongly opinionated about TDD, a poor fit for teams that don't do test-first development
- Documentation is scattered across files, raising troubleshooting cost
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Claude Code Sub-Agent Collective This agent | 56 · Major gaps | — | ★ 526 | 7mo ago | JavaScript | Claude Code |
| Ordewell | 87 · Good | CLIFree + model costs | ★ 212 | today | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| PowerContext | 82 · Good | CLIFree | ★ 1.8k | today | Python | Codex · Claude Code |
| Agent Design Patterns (ADPS) | 72 · Some gaps | Library / SDKFree | ★ 353 | 4d ago | HTML | — |
How does FollowAgents rate this agent?
Why each dimension lost points
The installer writes .claude/settings.json, 30+ agent definitions, and hook scripts into the user's project; hooks enforce behavior changes, a broad footprint. Aside from interactive init, there is no explicit user confirmation for hook injection or metrics collection; metrics are stored locally under .claude-collective/metrics but the data scope and retention are undocumented. Dependencies are common packages but only caret-ranged, with no audit/lockfile evidence. External effects (Context7 network calls, file writes) are described but not minimized. Positive: clean/repair/validate provide installation-level rollback (2). Deduction: package.json's repository URL points to anthropics/claude-code-sub-agent-collective while the actual repo is vanzan01 — inaccurate source attribution.
Self-contradiction: README says @task-orchestrator is the routing hub; CLAUDE.md says hub-and-spoke uses @routing-agent as central coordinator (deducted). Dependencies are reasonable (Node>=16), but Context7 is an external service whose connectivity failures are acknowledged (2). Failure handling is decent: validate/status/repair diagnostics and a troubleshooting section covering install failure, hooks not loading, and tests not running (2).
Audience is clear (personal MVP/prototyping, TDD-oriented) with --minimal etc. options (2). 'What it is and isn't' plus the honest-assessment section define capability boundaries very well (3). Trigger precision is weak: routing 'usually picks the right agent' is experiential with no routing-rule or accuracy evidence (1). Environment fit is documented (Node version, restart requirement, MCP/hook support) but the hook restart requirement is a fragility (2).
README admits 'Documentation is scattered across files' (1). Install notes are thorough: options, installed-file tree, validation steps (3). Naming is broadly consistent (@agent prefixes, ccc-* test-directory convention) with some drift across docs (2). Command docs are example-rich but the FAQ leans on troubleshooting (2). Known-limitations section is honest and detailed (3). MIT LICENSE file complete and consistent (3). Version 2.0.8 with CHANGELOG referenced but its content not in evidence (2). Maintenance is a declared side project with slow responses — responsibility boundaries clear but continuity unguaranteed (2).
Outputs are usable: standardized TDD completion reports and quality gates (2). Real marginal value for TDD workflows (tests-first, Context7 lookup), though the core research hypotheses (H1/H2/H3) have target thresholds but no published validation results (2). Cost/benefit is weak: full install of 30+ agents, self-admitted over-thoroughness, slow research phase — heavy overhead for simple tasks (1).
Performance claims (<50ms simple commands) and research targets (30% context reduction) are asserted without measurement data (1). Cross-source corroboration fails internally (contradictory hub agent names; wrong repository URL in package.json) (1). Positive: the project consistently labels itself experimental, personal, 'use at your own risk' — fact/inference separation is reasonably good (2).
- package.json's repository URL points to the anthropics org while the actual repo is vanzan01/claude-code-sub-agent-collective — treat provenance metadata as unreliable and verify independently.
- Installation writes .claude/settings.json and hook scripts into your project, changing Claude Code behavior; inspect hook contents before installing and note that a Claude Code restart is required.
- The metrics system records usage data under .claude-collective/metrics with no documented data scope or retention policy; task content may be written to local files.
- README and CLAUDE.md contradict each other on the hub agent (task-orchestrator vs routing-agent); trust observed behavior over the docs.
- Performance claims and research hypotheses are presented without validation data; do not treat them as proven benefits.
- Suitable only for prototyping/personal projects; the author explicitly states it is not production-ready and maintenance responses are slow — do not use where security or stability is required.
FAQ
Is Claude Code Sub-Agent Collective open source?
Is Claude Code Sub-Agent Collective safe to use?
Is Claude Code Sub-Agent Collective still maintained?
Who makes Claude Code Sub-Agent Collective?
Thanks — we use this to improve the page.