supaclaude

Bootstrap specialist AI agents into any project, then launch Claude Code.

Install

npm install -g @anthropic-ai/claude-code
npm install -g supaclaude

Usage

cd your-project/
supaclaude

That's it. supaclaude creates the agent files in your project directory and launches claude.

All arguments are passed through to claude:

supaclaude "fix the login bug"      # launch with a prompt
supaclaude --resume                 # resume a previous session
supaclaude --model opus             # pick a model

What it creates

your-project/
  CLAUDE.md              ← Orchestrator rules (how agents coordinate)
  PROJECT_BIBLE.md       ← Living knowledge base
  .agents/
    drift.md             ← Drift Detective
    dependency.md        ← Dependency Sentinel
    bible.md             ← Project Bible keeper
    flagging.md          ← Flagging Agent (spec referee)
    anti-vibe.md         ← Anti-Vibe Code (AI artifact detector)

Safe to run repeatedly — existing files are never overwritten.

The Agents

Drift Detective

Detects configuration drift between your intended state (code, config, docker-compose) and the actual running environment. Run it before deploys or after infrastructure changes.

"Run the Drift Detective on the current environment."

Dependency Sentinel

Audits dependency health across all services — security vulnerabilities, outdated packages, license issues. Supports npm, pip, Go modules, Cargo, Bundler, Composer, and more.

"Run the Dependency Sentinel across all services."

Project Bible

Maintains PROJECT_BIBLE.md as a living record of architecture decisions, completed features, incidents, and conventions. Keeps institutional knowledge from getting lost.

"Update the Project Bible based on what was just done."

Flagging Agent

A requirement adherence referee. Two modes: before a build it turns rough requirements into a formal SPEC.md with acceptance criteria. After a build it checks every requirement against the implementation and throws flags — MISSING, DRIFT, PARTIAL, GHOST, or ASSUMPTION. It does not suggest fixes. It calls the foul, cites the rule, spots the ball.

"Run the Flagging Agent to spec out [feature description]." "Run the Flagging Agent against specs/[feature-slug]/SPEC.md."

Anti-Vibe Code

Detects code that was generated by AI and accepted without being read critically. Catches emoji in source code, inconsistent naming conventions, hallucinated comments, mixed UI styling systems, AI boilerplate, dead code clusters, inconsistent error handling, and magic numbers. It doesn't care if AI was used — it cares if the output was reviewed.

"Run the Anti-Vibe agent on the recent changes."

Orchestrator Rules

The generated CLAUDE.md enforces these rules across all agents:

1. Never modify production databases without explicit confirmation
2. Never push to git without running tests first
3. If a task is ambiguous, write a CLARIFY.md listing questions — don't guess
4. Log all significant actions to PROJECT_BIBLE.md via the Bible agent
5. Prefer reversible changes; flag irreversible ones
6. Each agent stays within its defined scope

Requirements

• Claude Code (npm install -g @anthropic-ai/claude-code)
• Node.js >= 18

License

MIT