ClaudeCatalyst

Supercharge Claude Code — auto-routing, model delegation, session persistence, project-aware config.

One command to transform Claude Code from a basic assistant into an intelligent development pipeline that knows your project, remembers your sessions, and routes tasks to the right model.

Quick Install

# One-time run (no global install needed)
npx claude-catalyst@latest init

# Or install globally for easy access
npm install -g claude-catalyst@latest
claude-catalyst init

That's it. Open a new Claude Code session and type /catalyst to start.

What It Does

ClaudeCatalyst adds 6 slash commands to Claude Code:

| Command | Description | |---------|-------------| | /catalyst [task] | Main orchestrator — analyzes your task, classifies complexity, routes to the right pipeline | | /catalyst-new | Scaffold a new project with full setup | | /catalyst-learn | Analyze an existing project — tech stack, conventions, patterns | | /catalyst-save | Save session state before switching context | | /catalyst-load | Restore previous session — pick up where you left off | | /catalyst-mode q\|b\|e | Switch between quality, balanced, and eco modes |

How It Works

Complexity-Based Routing

When you run /catalyst [task], it classifies your task and picks the right workflow:

TRIVIAL  (< 2 min)  →  Direct fix, no ceremony
SMALL    (2-10 min) →  Delegate to Sonnet
MEDIUM   (10-30 min) → Brainstorm → Plan → TDD → Implement → Review
LARGE    (30+ min)  →  Full GSD pipeline with quality gates

Model Delegation

Not every task needs the most expensive model:

| Task | Model | Why | |------|-------|-----| | File search, grep, exploration | Haiku | Fast & cheap | | Implementation, tests, refactoring | Sonnet | Good balance | | Architecture, planning, orchestration | Opus | When it matters |

Three Modes

Switch anytime with /catalyst-mode:

| Mode | Effort | Opus | Quality Gates | |------|--------|------|---------------| | quality | xhigh | Everything | All | | balanced | high | Plan + review | Relevant ones | | eco | medium | Critical decisions only | Security only |

Session Persistence

/catalyst-save    →  Saves what you did, decisions made, open tasks
/catalyst-load    →  New session picks up exactly where you left off

No more "what were we working on?" — sessions are stored in .catalyst/sessions/ inside your project.

Project Awareness

/catalyst-learn scans your project and remembers:

• Framework, language, styling approach
• Test framework and commands
• File naming conventions, export patterns
• Directory structure

Stored in .catalyst/stack.md — every future /catalyst call uses this context.

Installation

Full Install (recommended)

Installs everything — global skills + project-level config:

npx claude-catalyst@latest init

Install Globally (optional)

Install once, use everywhere without npx:

npm install -g claude-catalyst@latest
claude-catalyst init

Update to latest version:

npm install -g claude-catalyst@latest

Global Only

Installs skills, hooks, plugins, settings, CLI tools, and MCP servers to ~/.claude/. Run this once per machine — all projects benefit from it.

npx claude-catalyst@latest init --global

What it installs:

• 13 skills:
  • Catalyst core — /catalyst, /catalyst-new, /catalyst-learn, /catalyst-save, /catalyst-load, /catalyst-mode
  • Quality tools — /a11y-audit, /dead-code, /dup-check, /perf-check, /security-audit
  • Generators — /doc-gen (Word/PDF), /ui-ux-pro-max (design system, 161 palettes, 67 UI styles)
• Hooks — secret-guard (blocks commits containing API keys/passwords)
• Plugins — Superpowers (structured workflows), Trail of Bits (static analysis)
• MCP servers — Playwright (browser automation), WebSearch (DuckDuckGo), Beads (task tracking)
• CLI tools — Semgrep (static analysis), CodeQL (security scanning), skill-seekers, beads-mcp
• Settings — marketplace configs for plugin updates

After this, /catalyst commands work in every project.

Project Only

Sets up ClaudeCatalyst for a specific project. Run this inside your project directory:

cd my-project
npx claude-catalyst@latest init --project

What it installs:

• .claude/settings.json — safe permissions:
  • Allows: git read commands, npm run, node, npx
  • Denies: rm -rf, git push --force, reading .env files
• .catalyst/ — session storage directory
  • sessions/ — saved sessions (gitignored)
  • stack.md — project tech stack (created by /catalyst-learn)
  • mode.json — active mode (created by /catalyst-mode)
• CLAUDE.md — auto-detected tech stack and conventions
• .gitignore — adds .catalyst/sessions/ to gitignore

Per-Project Workflow

After global install, this is the recommended flow for each new project:

# 1. Set up project-level config
cd my-project
npx claude-catalyst@latest init --project

# 2. Open Claude Code and let it learn your project
/catalyst-learn

# 3. Start working
/catalyst add authentication system

Update & Health Check

# Update skills to latest version
claude-catalyst update        # if installed globally
npx claude-catalyst@latest update  # if using npx

# Check what's installed and what's missing
claude-catalyst doctor

# Auto-fix any issues found by doctor
claude-catalyst heal

Health Check

claude-catalyst doctor

Skills:
  ✅ /catalyst
  ✅ /catalyst-new
  ✅ /catalyst-learn
  ✅ /catalyst-save
  ✅ /catalyst-load
  ✅ /catalyst-mode

Hooks:
  ✅ secret-guard hook

Settings:
  ✅ Superpowers plugin enabled
  ✅ Trail of Bits plugin enabled

MCP Servers:
  ✅ playwright
  ✅ websearch
  ✅ beads

████████████████████ 100% (22/22)

Requirements

• Node.js 18+
• Claude Code CLI installed
• Git
• Python 3.x (optional — for semgrep, beads-mcp, skill-seekers)

License

MIT