Claude Studio

oh-my-zsh for Claude Code — 11 specialist agents, 40+ automation commands, 15 hooks, and 9 coding rules in one package.

Claude Studio is a plugin framework that transforms Claude Code into a production-grade development environment. Install it in any project to get TDD workflows, automated code review, security scanning, and one-command pipelines — all without touching your global config.

What Changes

| Vanilla Claude Code | + Claude Studio | |---|---| | Manual workflow | /auto runs plan → code → test → review → commit | | Single agent | 11 specialist agents with role separation | | No security checks | Automatic secret filtering, OWASP scanning | | No code review | /code-review for 2-stage quality review | | Ad-hoc testing | /tdd enforces RED → GREEN → REFACTOR |

Installation

Via npm (Recommended)

# In your project directory
npx @leegrit/claude-studio init

This creates project-level configuration only — your global ~/.claude/ is never modified.

Via install script

# macOS / Linux / WSL
bash install.sh

# Windows
powershell install.ps1

Verify

npx @leegrit/claude-studio status

What gets created

your-project/
├── .claude/
│   ├── settings.json          # Merged settings (hooks, permissions, env)
│   └── work-log/              # Session tracking
├── .claude-plugin/
│   └── plugin.json            # Plugin manifest with resolved paths
└── .claude-studio.json        # Your overrides (customization entry point)

Quick Start

# Start Claude Code in your project
claude

# Option 1: Full auto — one line does everything
/auto Add user login with JWT authentication

# Option 2: Step by step
/plan Add user login with JWT authentication
/tdd
/code-review
/handoff-verify
/commit-push-pr

Run /guide for an interactive 3-minute tutorial.

Core Concepts

1. Agents = Specialists

Each agent is an expert in a specific domain. Commands invoke the right agent automatically, or you can call them directly.

| Agent | Role | When to Use | |---|---|---| | planner | Implementation planning (3-6 steps) | Before starting new features | | architect | System design analysis (read-only) | Architecture decisions | | tdd-guide | Test-driven development | Writing tests and code | | code-reviewer | 2-stage code quality review | After completing code | | security-reviewer | OWASP Top 10 + STRIDE analysis | Auth, payment, session code | | build-error-resolver | Build failure debugging | When builds break | | database-reviewer | Schema, query, index review | Database-related code | | refactor-cleaner | Dead code removal, cleanup | Code maintenance | | doc-updater | Auto-generate docs, changelogs | Documentation sync | | e2e-runner | Playwright E2E tests | Integration testing | | verify-agent | Independent pre-commit check | Before committing |

2. Commands = Workflows

Slash commands (/) orchestrate multi-step workflows. They combine agents, tools, and checks into a single invocation.

3. Hooks = Safety Nets

Hooks run automatically in the background — blocking dangerous commands, masking secrets in output, triggering security scans after code changes, and tracking work sessions.

Commands

One-Button Automation

/auto <task description>

Automatically selects the right pipeline and effort level:

| Effort | Steps | When | |---|---|---| | quick | TDD → Commit | 1-2 file changes, config/text edits | | standard | Plan → TDD → Verify → Commit | Normal features and bugfixes | | full | Plan → TDD → Code Review → Verify → Commit → Sync Docs | Large features, security-sensitive code |

Override with flags:

/auto --effort full --mode bugfix Payment returns $0

All Commands

| Command | Description | |---|---| | /plan | Create implementation plan (3-6 steps) | | /explore | Analyze codebase and find relevant code | | /sync | Restore context from previous session | | /guide | Interactive usage tutorial |

| Command | Description | |---|---| | /tdd | Test-driven development cycle | | /build-fix | Auto-fix build errors | | /refactor-clean | Remove dead code, reduce complexity | | /init-project | Initialize new project with CLAUDE.md |

| Command | Description | |---|---| | /code-review | 2-stage code review (spec + quality) | | /security-review | OWASP + STRIDE security analysis | | /handoff-verify | Build + test + lint verification | | /verify-loop | Verify with auto-fix retry | | /test-coverage | Test coverage analysis | | /e2e | End-to-end test execution |

| Command | Description | |---|---| | /commit-push-pr | Commit → push → create PR | | /quick-commit | Fast commit + push | | /checkpoint | Save work snapshot | | /pull | Fetch and update | | /worktree-start | Create isolated git worktree | | /worktree-cleanup | Clean up worktrees |

| Command | Description | |---|---| | /sync-docs | Auto-sync documentation | | /update-docs | Manual documentation update | | /update-codemaps | Generate codebase maps |

| Command | Description | |---|---| | /show-setup | Display current configuration | | /studio-update | Check for framework updates | | /agent-router | Route to specific agent | | /orchestrate | Multi-agent coordination | | /eval | Code quality evaluation | | /suggest-automation | Find automation opportunities | | /learn | Knowledge retrieval |

Hooks (Automatic)

These run in the background without any user action:

| Trigger | Hook | What It Does | |---|---|---| | Session start | context-sync-suggest | Suggests /sync if time has passed | | Session start | studio-update-check | Notifies of new versions | | Before bash | remote-command-guard | Blocks dangerous commands (rm -rf /, etc.) | | Before MCP call | rate-limiter | Limits MCP calls (30/min) | | After code edit | code-quality-reminder | Quality checklist reminder | | After code edit | security-auto-trigger | Auto security scan | | Tool output | output-secret-filter | Masks API keys, tokens in output | | Session end | session-wrap-suggest | Suggests session summary |

Pipelines

The /auto command runs a configurable pipeline. Three built-in modes:

feature:  Plan → TDD → Code Review → Verify → Commit & PR → Sync Docs
bugfix:   Explore → TDD → Verify → Quick Commit → Sync Docs
refactor: Refactor → Code Review → Verify → Commit & PR → Sync Docs

Custom Pipelines

Copy the default and edit:

cp node_modules/@leegrit/claude-studio/pipeline.default.json .claude/pipeline.json

Example — adding a database review step:

{
  "version": 1,
  "pipelines": {
    "feature": {
      "steps": [
        { "name": "Plan",        "command": "plan",            "min_effort": "standard" },
        { "name": "TDD",         "command": "tdd" },
        { "name": "DB Review",   "command": "database-review", "min_effort": "standard" },
        { "name": "Code Review", "command": "code-review",     "min_effort": "full" },
        { "name": "Verify",      "command": "handoff-verify",  "min_effort": "standard" },
        { "name": "Commit & PR", "command": "commit-push-pr" },
        { "name": "Sync Docs",   "command": "sync-docs",       "min_effort": "full", "on_fail": "continue" }
      ]
    }
  }
}

| Field | Required | Description | |---|---|---| | name | Yes | Display name in pipeline output | | command | Yes | Slash command to execute | | args | No | Arguments for the command | | min_effort | No | Minimum effort level to run (standard, full) | | on_fail | No | "stop" (default) or "continue" |

Customization

All customization goes through .claude-studio.json in your project root. This file is created during init — edit it and run npx @leegrit/claude-studio update to apply.

{
  "hooks": {
    "disable": ["rate-limiter"],           // Turn off specific hooks
    "add": { "PreToolUse": [{ ... }] },    // Add custom hooks
    "replace": { "remote-command-guard": { ... } }  // Replace hooks
  },
  "permissions": {
    "additionalAllow": ["WebFetch(*)"],    // Allow more tools
    "additionalDeny": ["Bash(rm -rf *)"]   // Block more patterns
  },
  "env": {
    "MY_VAR": "value"                      // Add environment variables
  },
  "disable": {
    "agents": ["doc-updater"],             // Disable specific agents
    "commands": ["quick-commit"],          // Disable specific commands
    "rules": ["date-calculation"],         // Disable specific rules
    "skills": ["eval-harness"]             // Disable specific skills
  },
  "pipeline": "custom"                     // Use .claude/pipeline.json
}

MCP Servers

Claude Studio configures these MCP servers at the project level:

| Server | Purpose | |---|---| | context7 | Real-time library docs (React, Next.js, etc.) | | memory | Persistent knowledge graph across sessions | | exa | AI-powered web search | | github | GitHub repo/PR/issue management | | fetch | Web content fetching | | jina-reader | URL-to-markdown conversion |

Rules

9 coding principles enforced across all agents:

• Design first — 3+ file changes require /plan before coding
• Test first — RED → GREEN → REFACTOR with 80%+ coverage
• Evidence-based completion — show test results, not assumptions
• Small units — files < 800 lines, functions < 50 lines, nesting < 4 levels
• Immutability — spread operators, never mutate originals
• Secrets in env vars — zero hardcoded credentials
• Security gates — auth/payment code requires /security-review
• Surgical changes — only modify what was requested
• Input validation — validate at system boundaries

CLI Reference

npx @leegrit/claude-studio init      # First-time setup
npx @leegrit/claude-studio update    # Re-merge after config changes
npx @leegrit/claude-studio eject     # Copy everything inline, remove npm dep
npx @leegrit/claude-studio status    # Show installation state

Eject

If you want to remove the npm dependency and keep all files locally:

npx @leegrit/claude-studio eject

This copies all agents, commands, hooks, rules, and skills into your project and removes the npm package reference.

Project Structure

claude-studio/
├── agents/            # 11 specialist agent definitions
├── commands/          # 40+ slash commands
├── skills/            # 15 reusable skill modules
├── hooks/             # 15 automation hooks
├── rules/             # 9 coding principles
├── cc-chips-custom/   # Status bar customization
├── knowledge/         # Reference documentation
├── scripts/           # Utility scripts
├── bin/cli.js         # CLI entry point
├── lib/               # Core library (init, update, merge, eject)
├── templates/         # Default configuration templates
├── settings.base.json # Base settings (merged during init)
├── pipeline.default.json  # Default pipeline definitions
└── mcp-servers.json   # MCP server configurations

Requirements

• Node.js >= 18
• Claude Code (Anthropic CLI)
• Git (for hooks and worktree features)

License

MIT