npm package: @leegrit/claude-studio
Description: oh-my-zsh for Claude Code — professional agents, automation commands, security hooks, and quality rules
Author: leegrit
Latest version: 1.0.1

# 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](https://docs.anthropic.com/en/docs/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)

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

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

### Via install script

```bash
# macOS / Linux / WSL
bash install.sh

# Windows
powershell install.ps1
```

### Verify

```bash
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

```bash
# 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

```bash
/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:

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

### All Commands

<details>
<summary><strong>Planning & Discovery</strong></summary>

| 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 |

</details>

<details>
<summary><strong>Development</strong></summary>

| 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 |

</details>

<details>
<summary><strong>Quality & Security</strong></summary>

| 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 |

</details>

<details>
<summary><strong>Git & PR</strong></summary>

| 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 |

</details>

<details>
<summary><strong>Documentation</strong></summary>

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

</details>

<details>
<summary><strong>Utilities</strong></summary>

| 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 |

</details>

---

## 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:

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

Example — adding a database review step:

```json
{
  "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.

```jsonc
{
  "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

```bash
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:

```bash
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](LICENSE)