superclaude-org--superclaude_framework/docs/user-guide/claude-code-integration.md

# Claude Code Integration Guide

How SuperClaude integrates with — and extends — Claude Code's native features.

## Overview

SuperClaude enhances Claude Code through **context engineering**. It doesn't replace Claude Code — it configures and extends it with specialized commands, agents, modes, and development patterns through Claude Code's native extension points.

This guide maps every SuperClaude feature to its Claude Code integration point, and identifies gaps where SuperClaude could better leverage Claude Code's capabilities.

---

## Integration Points

### 1. Slash Commands → Claude Code Custom Commands

**Claude Code native**: Reads `.md` files from `~/.claude/commands/` and makes them available as `/` commands. Supports YAML frontmatter, argument substitution (`$ARGUMENTS`, `$0`, `$1`), dynamic context injection (`` !`command` ``), and subagent execution (`context: fork`).

**SuperClaude provides**: 30 slash commands installed to `~/.claude/commands/sc/`, namespaced as `/sc:*`.

| Category | Commands |
|----------|----------|
| **Planning & Design** | `/sc:pm`, `/sc:brainstorm`, `/sc:design`, `/sc:estimate`, `/sc:spec-panel` |
| **Development** | `/sc:implement`, `/sc:build`, `/sc:improve`, `/sc:cleanup`, `/sc:explain` |
| **Testing & Quality** | `/sc:test`, `/sc:analyze`, `/sc:troubleshoot`, `/sc:reflect` |
| **Documentation** | `/sc:document`, `/sc:help` |
| **Version Control** | `/sc:git` |
| **Research** | `/sc:research`, `/sc:business-panel` |
| **Project Management** | `/sc:task`, `/sc:workflow` |
| **Utilities** | `/sc:agent`, `/sc:index-repo`, `/sc:recommend`, `/sc:select-tool`, `/sc:spawn`, `/sc:load`, `/sc:save` |

**Installation**: `superclaude install`

### 2. Agents → Claude Code Custom Subagents

**Claude Code native**: Supports custom subagent definitions in `~/.claude/agents/` (user) and `.claude/agents/` (project). Agents have YAML frontmatter with `model`, `allowed-tools`, `effort`, `context`, and `hooks` fields. Invocable via `@agent-name` syntax. 6 built-in subagents: Explore, Plan, General-purpose, Bash, statusline-setup, Claude Code Guide.

**SuperClaude provides**: 20 domain-specialist agents installed to `~/.claude/agents/`.

| Agent | Specialization |
|-------|---------------|
| `@pm-agent` | Project management, PDCA cycles, context persistence |
| `@system-architect` | System design, architecture decisions |
| `@frontend-architect` | UI/UX, component design, accessibility |
| `@backend-architect` | APIs, databases, infrastructure |
| `@security-engineer` | Security audit, vulnerability analysis |
| `@deep-research` | Multi-source research with citations |
| `@deep-research-agent` | Alternative research agent |
| `@quality-engineer` | Testing strategy, code quality |
| `@performance-engineer` | Optimization, profiling, benchmarks |
| `@python-expert` | Python-specific best practices |
| `@technical-writer` | Documentation, API docs |
| `@devops-architect` | CI/CD, deployment, infrastructure |
| `@refactoring-expert` | Code refactoring patterns |
| `@requirements-analyst` | Requirements engineering |
| `@root-cause-analyst` | Root cause analysis |
| `@socratic-mentor` | Teaching through questions |
| `@learning-guide` | Learning path guidance |
| `@self-review` | Code self-review |
| `@repo-index` | Repository indexing |
| `@business-panel-experts` | Business stakeholder analysis |

**Installation**: `superclaude install` (installs both commands and agents)

### 3. Behavioral Modes

**Claude Code native**: Supports permission modes (`default`, `plan`, `acceptEdits`, `bypassPermissions`), effort levels (`low`, `medium`, `high`, `max`), and extended thinking. No direct "behavioral mode" concept — SuperClaude adds this through context injection.

**SuperClaude provides**: 7 behavioral modes that adapt Claude's response patterns:

| Mode | Effect | Claude Code Mapping |
|------|--------|-------------------|
| **Brainstorming** | Divergent thinking, idea generation | Context injection via command |
| **Business Panel** | Multi-stakeholder analysis | Multi-agent orchestration |
| **Deep Research** | Systematic investigation with citations | Extended thinking + research agent |
| **Introspection** | Self-reflection, meta-analysis | Extended thinking context |
| **Orchestration** | Multi-agent coordination | Subagent delegation |
| **Task Management** | PDCA cycles, progress tracking | TodoWrite + session persistence |
| **Token Efficiency** | Minimal token usage, concise responses | Effort level adjustment |

### 4. Skills → Claude Code Skills System

**Claude Code native**: Full skills system with YAML frontmatter (`name`, `description`, `allowed-tools`, `model`, `effort`, `context`, `agent`, `hooks`), argument substitution, dynamic context injection, subagent execution, and auto-discovery in `.claude/skills/` directories. Skills can be user-invocable or auto-triggered.

**SuperClaude provides**: 1 skill currently (`confidence-check`). This is a significant gap — many SuperClaude commands could be reimplemented as proper Claude Code skills for better integration.

**Installation**: `superclaude install-skill <name>`

### 5. Hooks → Claude Code Hooks System

**Claude Code native**: 28 hook event types with 4 handler types (command, HTTP, prompt, agent). Events include `SessionStart`, `SessionEnd`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, `PreCompact`, `PostCompact`, `TaskCompleted`, `WorktreeCreate`, and more. Hooks are configured in `settings.json` under the `hooks` key.

**SuperClaude provides**: Hook definitions in `src/superclaude/hooks/hooks.json`. Currently limited — does not leverage many available hook events.

**Gap**: SuperClaude could use hooks for:
- `SessionStart` — Auto-restore PM Agent context
- `PostToolUse` — Self-check validation after edits
- `Stop` — Session summary and next-actions persistence
- `TaskCompleted` — Reflexion pattern trigger
- `SubagentStop` — Quality gate checks

### 6. Settings → Claude Code Settings System

**Claude Code native**: 5 settings scopes (managed, CLI flags, local project, shared project, user). Supports permissions (`allow`/`ask`/`deny`), tool-specific rules with wildcards (`Bash(npm *)`, `Edit(/path/**)`), sandbox configuration, model overrides, auto-memory, and MCP server management.

**SuperClaude provides**: Project-level `.claude/settings.json` with basic permission rules.

**Gap**: Could provide recommended settings profiles for different workflows (e.g., strict security mode, autonomous development mode, research mode).

### 7. MCP Servers → Claude Code MCP Integration

**Claude Code native**: Supports stdio and SSE transports, OAuth authentication, 3 configuration scopes (local, project, user), tool search, channel push notifications, and elicitation (interactive input). 60+ servers in the official registry.

**SuperClaude provides**: 8 pre-configured servers + AIRIS Gateway:

| Server | Purpose | Transport |
|--------|---------|-----------|
| **AIRIS Gateway** | Unified gateway with 60+ tools | SSE |
| **Tavily** | Web search for deep research | stdio |
| **Context7** | Official library documentation | stdio |
| **Sequential Thinking** | Multi-step problem solving | stdio |
| **Playwright** | Browser automation and E2E testing | stdio |
| **Serena** | Semantic code analysis | stdio |
| **Magic** | UI component generation | stdio |
| **MorphLLM** | Fast Apply for code modifications | stdio |

**Installation**: `superclaude mcp` (interactive) or `superclaude mcp --servers tavily context7`

### 8. Pytest Plugin (Auto-loaded)

**Claude Code native**: No built-in test framework — relies on tool use (`Bash`) to run tests.

**SuperClaude adds**: Auto-loaded pytest plugin registered via `pyproject.toml` entry point.

**Fixtures**: `confidence_checker`, `self_check_protocol`, `reflexion_pattern`, `token_budget`, `pm_context`

**Auto-markers**: Tests in `/unit/` → `@pytest.mark.unit`, `/integration/` → `@pytest.mark.integration`

**Custom markers**: `confidence_check`, `self_check`, `reflexion`, `complexity`

---

## Feature Mapping: Claude Code ↔ SuperClaude

| Claude Code Feature | SuperClaude Enhancement | Gap? |
|--------------------|------------------------|------|
| 60+ built-in `/` commands | 30 custom `/sc:*` commands | Complementary |
| 6 built-in subagents | 20 domain-specialist `@agents` | Complementary |
| Skills system (YAML + MD) | 1 skill (confidence-check) | **Large gap** — should convert commands to skills |
| 28 hook events | Basic hook definitions | **Large gap** — most events unused |
| 5 settings scopes | 1 project scope used | **Medium gap** — no recommended profiles |
| Permission modes (4) | Not leveraged | **Gap** — could provide mode presets |
| Extended thinking | Deep Research mode uses it | Partial |
| Agent teams (preview) | Orchestration mode | Partial alignment |
| Voice dictation (20 langs) | Not leveraged | Not applicable |
| Desktop app features | Not leveraged | Not applicable (CLI-focused) |
| Plan mode | Not leveraged | **Gap** — could integrate with confidence checks |
| Session persistence | PM Agent memory files | Partial — could use native sessions |
| `/compact` context mgmt | Token Efficiency mode | Partial alignment |
| MCP 60+ registry servers | 8 pre-configured + gateway | Partial |
| Worktree isolation | Documented in CLAUDE.md | Documented |
| `--effort` levels | Token Efficiency mode | Partial alignment |
| `/batch` parallel changes | Parallel execution engine | Complementary |
| Fast mode | Not leveraged | Not applicable |

---

## Key Gaps to Address

### High Priority

1. **Skills Migration**: Convert key `/sc:*` commands into proper Claude Code skills with YAML frontmatter. This enables auto-triggering, tool restrictions, effort overrides, and better IDE integration.

2. **Hooks Integration**: Leverage Claude Code's 28 hook events for:
   - `SessionStart` → PM Agent context restoration
   - `Stop` → Session summary persistence
   - `PostToolUse` → Self-check after edits
   - `TaskCompleted` → Reflexion pattern

3. **Plan Mode Integration**: Connect confidence checks with Claude Code's native plan mode — block implementation when confidence < 70%.

### Medium Priority

4. **Settings Profiles**: Provide recommended `.claude/settings.json` profiles for different workflows (strict security, autonomous dev, research).

5. **Native Session Persistence**: Use Claude Code's `--continue` / `--resume` instead of custom memory files for PM Agent context.

6. **Permission Presets**: Pre-configured permission rules for SuperClaude's common workflows.

### Future (v5.0+)

7. **TypeScript Plugin System**: Native Claude Code plugin marketplace distribution.
8. **IDE Extensions**: VS Code / JetBrains integration for SuperClaude features.
9. **Agent Teams**: Align Orchestration mode with Claude Code's agent teams feature.

---

## Claude Code Native Features Reference

For developers working on SuperClaude, these are the key Claude Code capabilities to be aware of:

| Feature | Documentation |
|---------|--------------|
| Custom commands | `~/.claude/commands/*.md` with YAML frontmatter |
| Custom agents | `~/.claude/agents/*.md` with model/tools/effort config |
| Skills | `~/.claude/skills/` with auto-discovery and argument substitution |
| Hooks | 28 events in `settings.json` → command/HTTP/prompt/agent handlers |
| Settings | 5 scopes: managed > CLI > local > shared > user |
| Permissions | `Bash(pattern)`, `Edit(path)`, `mcp__server__tool` rules |
| MCP | stdio/SSE transports, OAuth, 3 scopes, elicitation |
| Subagents | `Agent` tool with model/tools/isolation/background options |
| Plan mode | Read-only exploration, visual plan markdown |
| Extended thinking | `--effort max`, `Alt+T` toggle, `MAX_THINKING_TOKENS` |
| Voice | 20 languages, push-to-talk, `/voice` command |
| Session mgmt | Named sessions, resume, fork, 7-day persistence |
| Context | `/context` visualization, auto-compaction at ~95% |