# One command writes thirty agents, and the hooks need a restart

> claude-code-sub-agent-collective is an experimental npm installer that drops a hub-and-spoke set of test-driven agents, a CLAUDE.md and hook scripts into a project, with a /van command that routes each request to whichever specialist is meant to handle it.

**vanzan01/claude-code-sub-agent-collective** —   🧠 Context Engineering Research - Not just another agent collection, but using research and context engineering to function as a collective. Hub-and-spoke coordination through Claude   Code.

- Repository: https://github.com/vanzan01/claude-code-sub-agent-collective
- Stars: 521 · Forks: 59
- Language: JavaScript
- License: MIT
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/vanzan01-claude-code-sub-agent-collective

## init writes CLAUDE.md, an agents folder and two hook scripts

What lands in your project is worth knowing before you run it, because the installer edits the working tree rather than installing a library you import. One command, npx claude-code-collective init, creates CLAUDE.md holding the behavioural rules the agents are meant to follow, a .claude directory with settings.json for hook configuration, an agents directory holding thirty or more markdown agent definitions, and a hooks directory containing test-driven-handoff.sh and collective-metrics.sh. Alongside that it creates .claude-collective with a tests folder for the framework templates. One entry in the agent folder is not markdown at all: lib/research-analyzer.js, a JavaScript complexity analysis engine sitting alongside the agent definitions. The README calls the whole thing experimental, opinionated and built to speed up one author's own MVP work, and it lists Node 16 or newer, npm 8 or newer, and a Claude Code install with MCP support and a hook system as the requirements. The selective variants are flags on the same command:

```bash
npx claude-code-collective init
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 --interactive
```

## /van is a router, not an agent

The coordination model is hub and spoke, and the hub is a single command. /van is the entry point, and it does not do work itself: it routes to @task-orchestrator, which analyses the request and delegates to whichever specialist fits. From there the shape of a run is the same every time. Agents research first, pulling real documentation through Context7 instead of guessing at a library's API. Tests are written before any implementation. Implementation is the minimum needed to make those tests pass. Refactoring happens with the tests green. Delivery reports back what tests were added and what the results were. Around that hub sit the specialists, and the grouping tells you what each one is for: implementation agents for components, features, infrastructure, testing and polish, quality agents for review and validation gates, research agents for documentation lookup and requirement breakdown, and system agents for behavioural setup, hook integration and maintenance.

## The delivery report is a fixed template, which is the point

Every completed task ends with the same block: a delivery complete header, a line confirming tests were written first in the red phase, a line confirming the implementation passes them in the green phase, a line confirming refactoring with tests still green, and a test results line counting how many tests pass. Nothing about that template is clever, and that is the argument for it. An agent that reports completion in a fixed structure produces a comparable artifact every time, which means a reviewer can check whether the red phase happened instead of taking the word for it. The hooks are the enforcement side of the same idea: test-driven-handoff.sh handles the transition between phases and collective-metrics.sh records what happened. Those metrics are also the diagnostic. If research feels slow, the project points you at .claude-collective/metrics/ for timing data rather than asking you to guess.

## Hooks load at startup, so installation needs a restart

The most common failure after installing is not a bug, and the README names the cause twice. The hook system requires a restart, and it calls that a Claude Code limitation rather than something the installer can work around. Until Claude Code reloads, the hooks are on disk and not loaded, so tests that should have been written first are simply not enforced. The troubleshooting path is short and worth keeping: run node --version to confirm 16 or newer, check that .claude/settings.json exists, run the validate command, and restart. Two other failure modes get their own advice. If the installer itself failed, clear the npm cache with npm cache clean --force and retry with the force flag. If tests do not run at all, the likelier cause is the project rather than the collective, since it needs a test runner such as Jest or Vitest already in place, and the check is whether tests are actually being written to files.

## Selective installs change what ends up in your repository

The full install is not the only option, and the flags are the difference between a large diff and a small one. --minimal installs just the core agents for lightweight projects. --testing-only narrows it to the testing framework agents. --hooks-only installs the behavioural system and the hook scripts and nothing else, which is the option to reach for when you want the discipline without the orchestration. --interactive walks through the choices, and --force retries an installation that failed. After the fact there is a management surface rather than a reinstall: status reports what is installed and working, validate checks installation integrity, repair fixes a broken installation, and clean removes everything. Those five verbs are the whole lifecycle, so an install is meant to be reversible. Worth noting that clean is the only one of them that touches files outside .claude, since the collective also writes CLAUDE.md into the project root. The management surface is five subcommands:

```bash
npx claude-code-collective status
npx claude-code-collective validate
npx claude-code-collective repair
npx claude-code-collective clean
```

## Two test runners are configured side by side

The repository tests itself with two frameworks at once, which tells you something about how it grew. Both jest.config.js and vitest.config.js sit at the top level. The default test script runs vitest, and there is a watch script for it, while five other scripts hand the same job to Jest: a plain Jest run, a watch mode, coverage, and three filtered runs that select contracts, handoffs or agents by path pattern. So a contributor who runs npm test gets Vitest, and a contributor who runs the filtered scripts gets Jest, and both are supported paths in the same package. The project also depends on both in development, along with a JUnit reporter for CI and the Vitest UI. Two things follow for anyone extending it: a change can pass one runner and not the other, and the coverage report you get depends on which script produced it.

## The package metadata points at a repository that is not this one

Check the package metadata before you trust the rest of it. The repository field in package.json gives the URL as a claude-code-sub-agent-collective repository under the anthropics organisation, while the code itself lives under a personal account. Tools that read that field to open an issue or clone a source will land in the wrong place. The description string in the same file is also wider than the documentation: it promises TaskMaster Task ID integration and deterministic handoffs, and the README never mentions TaskMaster. Neither mistake breaks the installer, since the bin entry points at a local file and the install path is fetched by package name, but both are reasons to read the README rather than the manifest when you are deciding what you are installing. The manifest is otherwise accurate: MIT licence, Node 16 or newer, main at lib/index.js, and the executable at bin/claude-code-collective.js.

## Version 2.0.8 with no published release, last commit 2026-04-20

Maintenance is the part to weigh, and the honest version is that this is a personal project on a slow clock. The package version is 2.0.8 and the repository publishes no GitHub releases, so there is no tag to pin, no changelog to diff against in the usual way, and no published artifact list. The last push landed on 2026-04-20, which is a little under six months before this writing, so the project is not abandoned but it is not moving quickly either. The repository is not archived, and the tree carries the documents a maintained project would carry: a changelog, a contributing guide, a user guide and a testing guide, plus docs, templates, scripts and its own .claude-collective directory committed at the root. The project's own assessment section is unusually blunt about the rest, listing agents still being refined, a research phase that can be slow, hooks that need a restart, documentation scattered across files, and agents that can be too thorough for a simple task.

## Conclusion

This installer suits a solo developer or small team that has already decided it works test-first and wants that decision enforced rather than re-argued in every session, since the hooks are what turn the preference into a gate instead of a suggestion. It does not suit a project that wants tests optional, a codebase with no test runner at all, or anyone who will not restart their editor after every install. Four things to check before adopting it. Whether the version you get matches what you expect, since the package says 2.0.8 while the repository publishes no releases at all. Which selective install you want, because the flags change whether you get the whole collective or only hooks. Whether your Node and npm meet 16 and 8. And whether the documentation is where you need it, because the project itself calls its documentation scattered across files and its own research phase slow at times.

## FAQ

### What does npx claude-code-collective init install into my project?

It writes CLAUDE.md with behavioural rules, a .claude directory with settings.json, an agents folder holding thirty or more agent definitions including a JavaScript research analyzer, two hook scripts for test-driven handoff and metrics, and a .claude-collective directory with test framework templates.

### What does claude-code-sub-agent-collective need before it will work?

Node.js 16 or newer, npm 8 or newer, and a Claude Code install with MCP support and a hook system. A restart of Claude Code is required after installation so the hooks load.

### Why are the TDD hooks not running after I install it?

Because the hook system only loads at startup, which the project describes as a Claude Code limitation. Restart Claude Code, confirm .claude/settings.json exists, and run npx claude-code-collective validate to check the installation.

### How do I manage an existing installation of the collective?

Five commands cover the lifecycle: status to see what is installed, validate to check integrity, repair to fix a broken install, clean to remove everything, and --help. Selective installs use flags such as --minimal, --testing-only and --hooks-only.

### Is claude-code-sub-agent-collective production ready?

It is not presented that way. The project describes itself as an experimental development aid for rapid prototyping, a personal project used for the author's own MVPs, and explicitly not production-ready enterprise software or guaranteed to work perfectly.

## Sources

- [Issues](https://github.com/vanzan01/claude-code-sub-agent-collective/issues)
- [License: MIT](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/LICENSE)
- [README](https://github.com/vanzan01/claude-code-sub-agent-collective/blob/main/README.md)
- [vanzan01/claude-code-sub-agent-collective on GitHub](https://github.com/vanzan01/claude-code-sub-agent-collective)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vanzan01-claude-code-sub-agent-collective