OrchestKit Configuration

Interactive setup for customizing your OrchestKit installation.

Quick Start

/ork:configure

Step 1: Choose Preset

Use AskUserQuestion:

Step 2: Customize Skill Categories

Categories available:

• AI/ML (26 skills)
• Backend (15 skills)
• Frontend (8 skills)
• Testing (13 skills)
• Security (7 skills)
• DevOps (4 skills)
• Planning (6 skills)

Step 3: Customize Agents

Product Agents (6):

• market-intelligence
• product-strategist
• requirements-translator
• ux-researcher
• prioritization-analyst
• business-case-builder

Technical Agents (14):

• backend-system-architect
• frontend-ui-developer
• database-engineer
• llm-integrator
• workflow-architect
• data-pipeline-engineer
• test-generator
• code-quality-reviewer
• security-auditor
• security-layer-auditor
• debug-investigator
• metrics-architect
• rapid-ui-designer
• system-design-reviewer

Step 4: Configure Hooks

Safety Hooks (Always On):

• git-branch-protection
• file-guard
• redact-secrets

Toggleable Hooks:

• Productivity (auto-approve, logging)
• Quality Gates (coverage, patterns)
• Team Coordination (locks, conflicts)
• Notifications (desktop, sound)

CC 2.1.49 Managed Settings: OrchestKit ships plugin settings.json with default hook permissions. These are managed defaults — users can override them in project or user settings. Enterprise admins can lock managed settings via managed profiles.

Step 5: Configure MCPs (Optional)

All 5 MCPs ship enabled by default. Tavily requires an API key; agentation requires a local package install.

Why all enabled? OrchestKit ships 30+ Sonnet/Haiku subagents. While Opus 4.6 has native extended thinking, Sonnet and Haiku do not — they benefit from sequential-thinking. Tavily and agentation are used by specific agents (see mcpServers in agent frontmatter). CC's MCPSearch auto-defers schemas when overhead exceeds 10% of context, so token cost is managed automatically.

Background agents: MCP tools are NOT available in background subagents (hard CC platform limitation). Agents that need MCP tools must run in the foreground.

Already have these MCPs installed globally? If Tavily or memory are already in your ~/.claude/mcp.json, skip enabling them here to avoid duplicate entries. OrchestKit agents will use whichever instance Claude Code resolves first.

Step 6: CC 2.1.7 Settings (New)

Configure CC 2.1.7-specific features:

Turn Duration Display

Enable turn duration in statusline? [y/N]: y

Adds to settings.json:

{
  "statusline": {
    "showTurnDuration": true
  }
}

MCP Auto-Deferral Threshold

MCP deferral threshold (default 10%): 10

Adds to config.json:

{
  "cc217": {
    "mcp_defer_threshold": 0.10,
    "use_effective_window": true
  }
}

Effective Context Window Mode

Use effective context window for calculations? [Y/n]: y

When enabled:

• Statusline shows context_window.effective_percentage
• Compression triggers use effective window
• MCP deferral more accurate

Step 7: CC 2.1.20 Settings

Configure CC 2.1.20-specific features:

Task Deletion Support

Enable task deletion (status: "deleted")? [Y/n]: y

Enables orphan detection and automatic cleanup of blocked tasks.

PR Status Enrichment

Enable PR status enrichment at session start? [Y/n]: y

Detects open PRs on current branch and sets ORCHESTKIT_PR_URL / ORCHESTKIT_PR_STATE env vars.

Background Agent Permission Pre-Mapping

Enable permission profile suggestions for agents? [Y/n]: y

Shows recommended permission profiles when spawning agents.

Monorepo Multi-Directory Detection

Enable monorepo detection? [Y/n]: y

Detects monorepo indicators and suggests --add-dir usage.

CC 2.1.47: When added_dirs are already active, the monorepo detector automatically skips the --add-dir suggestion. The added_dirs field is now available in hook inputs for multi-directory awareness.

Team Plugin Distribution (CC 2.1.45+)

Share OrchestKit across a team using a shared directory:

# Create shared plugin directory
mkdir -p /shared/team/plugins/orchestkit

# Copy plugin files
cp -r plugins/ork/* /shared/team/plugins/orchestkit/

# Team members use --add-dir to pick up the shared plugin
claude --add-dir /shared/team/plugins

CC 2.1.45+ supports plugin_hot_reload — team members get updates without restarting their sessions.

enabledPlugins vs added_dirs: enabledPlugins is a CC-internal concept and is NOT exposed to hooks. The hook-accessible field for multi-directory awareness is added_dirs (available in HookInput since CC 2.1.47). Hooks can read input.added_dirs to detect which additional directories are active — useful for adapting behavior in multi-repo workspaces.

Monorepo Package Context (CC 2.1.49)

When added_dirs are active, OrchestKit's monorepo detector surfaces package names from each directory as session context. This helps agents understand which packages are in scope:

Multi-directory context active (3 dirs)
Packages: @myapp/api, @myapp/web, @myapp/shared
Each directory may have its own CLAUDE.md with targeted instructions.

Use claude --add-dir ./packages/api --add-dir ./packages/web to include specific packages.

Step 8: CC 2.1.23 Settings

Configure CC 2.1.23-specific features:

Spinner Verbs Customization

Replace default Claude Code spinner verbs ("Thinking", "Working", etc.) with custom branding:

Customize spinner verbs? [Y/n]: y

Adds to .claude/settings.json:

{
  "spinnerVerbs": {
    "mode": "replace",
    "verbs": [
      "Orchestrating",
      "Coordinating",
      "Synthesizing",
      "Analyzing",
      "Reasoning",
      "Crafting",
      "Architecting",
      "Validating",
      "Dispatching",
      "Assembling",
      "Engineering",
      "Composing"
    ]
  }
}

Options:

• mode: "replace" - Use only your custom verbs
• mode: "append" - Add your verbs to the defaults

OrchestKit-themed verbs focus on orchestration, architecture, and engineering actions.

Step 9: Optional Integrations

Use AskUserQuestion to offer optional third-party integrations:

Agentation (UI Annotation Tool)

Enable Agentation UI annotation tool? [y/N]: y

Agentation lets you annotate your app's UI in the browser and have Claude pick up the feedback automatically.

When enabled, perform these steps (idempotent — skip any step already done):

1. Install dependencies (check package.json first):

   npm install -D agentation agentation-mcp

2. Add MCP server to .mcp.json (skip if agentation key already exists):

   {
     "mcpServers": {
       "agentation": {
         "command": "npx",
         "args": ["-y", "agentation-mcp", "server"],
         "disabled": false
       }
     }
   }

3. Enable MCP server in Claude Code settings — add "agentation" to the enabledMcpjsonServers array in .claude/settings.local.json (create file if missing, skip if already listed):

   {
     "enabledMcpjsonServers": ["agentation"]
   }

4. Scaffold wrapper component — create a dev-only client component (skip if file already exists). Use the project's component directory (e.g. src/components/, components/, or app/components/):

   // agentation-wrapper.tsx
   "use client";
   
   import { Agentation } from "agentation";
   
   export function AgentationWrapper() {
     if (process.env.NODE_ENV !== "development") return null;
     return <Agentation endpoint="http://localhost:4747" webhookUrl="http://localhost:4747" />;
   }

   Then instruct the user to add <AgentationWrapper /> to their root layout.

5. CSP update (only if the project has a Content-Security-Policy): add http://localhost:4747 to the connect-src directive for development mode only.

Step 10: Preview & Save

Save to: ~/.claude/plugins/orchestkit/config.json

{
  "version": "1.0.0",
  "preset": "complete",
  "skills": { "ai_ml": true, "backend": true, ... },
  "agents": { "product": true, "technical": true },
  "hooks": { "safety": true, "productivity": true, ... },
  "mcps": { "context7": false, ... }
}

Related Skills

• ork:doctor: Diagnose configuration issues

References

• Presets
• MCP Configuration

References (2)

Mcp Config

MCP Configuration

MCPs (Model Context Protocol servers) enhance OrchestKit commands but are NOT required. Commands work without them - MCPs just add extra capabilities.

Available MCPs

Subagent Model Note: Sequential-thinking MCP is redundant for Opus 4.6+ (which has native adaptive thinking), but OrchestKit ships 30+ Sonnet/Haiku subagents that do not have native extended thinking. These subagents benefit from sequential-thinking for complex multi-step reasoning. Enable it for the subagent mix, not the parent model.

Default State

OrchestKit ships all 5 MCPs enabled in .mcp.json. Tavily requires an API key (TAVILY_API_KEY via 1Password) — it connects but tools fail without the key. Agentation requires npm install -D agentation-mcp.

Two-Layer MCP Control (CC 2.1.49)

CC uses two layers to determine which MCP servers are active. Understanding both prevents configuration contradictions.

Layer 1: .mcp.json — Server definitions and self-declaration

• "disabled": false (or omitted) → server process starts, tools load
• "disabled": true → server process does NOT start, 0 tokens consumed

Layer 2: settings.json / settings.local.json — User approval

• enableAllProjectMcpServers: true → overrides Layer 1's disabled flag for all servers
• enabledMcpjsonServers: [...] → allowlist of approved servers
• disabledMcpjsonServers: [...] → denylist (takes precedence over allowlist)

Important: enableAllProjectMcpServers: true overrides disabled: true in .mcp.json. If you want a server truly off, either remove it from .mcp.json entirely or add it to disabledMcpjsonServers in settings.

OrchestKit ships .mcp.json with all servers disabled: false and settings.local.json with an enabledMcpjsonServers allowlist. No contradictions.

Per-Agent MCP Scoping (CC 2.1.49)

Agent frontmatter supports mcpServers to control which MCP servers a subagent can access:

---
name: web-research-analyst
mcpServers: [tavily]
---

• mcpServers omitted → agent inherits ALL MCP tools from parent session
• mcpServers: [tavily] → agent ONLY sees tavily tools
• mcpServers: [] → agent sees NO MCP tools

OrchestKit agents declare mcpServers explicitly to avoid inheriting unnecessary tool definitions into their smaller context windows (Sonnet: 128K vs Opus: 200K).

Background Agent Limitation

MCP tools are NOT available in background subagents. This is a hard CC platform limitation.

Agents spawned with run_in_background: true or background: true cannot call any MCP tools (tavily, context7, memory, sequential-thinking, agentation). Design background agents to use only built-in CC tools (Read, Grep, Glob, Bash, etc.).

If a background agent needs MCP tools, run it in the foreground instead.

Token Overhead & MCPSearch

Each connected MCP adds tool definitions to the context window:

MCPSearch (default since CC 2.1.7): When MCP tool schemas exceed 10% of the context window, CC automatically defers schema loading and uses an MCPSearch tool to discover tools on demand — reducing overhead by ~85%.

With 5 MCPs (~5.7K tokens = 2.8% of 200K), schemas load upfront. This is acceptable. If you add more MCPs and cross the 10% threshold, MCPSearch activates automatically.

Tighten the threshold: Set ENABLE_TOOL_SEARCH=auto:5 in your shell profile to defer at 5% instead of 10%.

Note: MCPSearch requires Sonnet 4+ or Opus 4+ — Haiku agents cannot use it and always get full schema overhead. OrchestKit's 2 Haiku agents (ci-cd-engineer, release-engineer) use mcpServers scoping to minimize their MCP exposure.

Enabling/Disabling MCPs

Edit .mcp.json and set "disabled": true or false for each MCP:

{
  "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/main/schemas/mcp.schema.json",
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "disabled": false
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
      "disabled": false
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": { "MEMORY_FILE": ".claude/memory/memory.json" },
      "disabled": false
    },
    "tavily": {
      "command": "sh",
      "args": ["-c", "TAVILY_API_KEY=$(op read 'op://Private/Tavily API Key/API Key') exec npx -y tavily-mcp@latest"],
      "disabled": false
    },
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"],
      "disabled": false
    }
  }
}

To disable a specific MCP, set "disabled": true in .mcp.json. Ensure settings.local.json does NOT have enableAllProjectMcpServers: true (which would override the disabled flag).

Tavily MCP

When TAVILY_API_KEY is set and the Tavily MCP is enabled, agents gain access to production-grade web research tools.

Tools

Which agents and skills use Tavily?

Setup

Option A: Local MCP with 1Password (recommended)

1. Get a free API key (1,000 credits/month): https://app.tavily.com
2. Store in 1Password: op item create --category "API Credential" --title "Tavily API Key" "API Key=tvly-..."
3. Use op read in .mcp.json (see example config above) — the sh -c wrapper fetches the key from 1Password at MCP startup

Note: Claude Code's MCP env block only resolves $\{ENV_VAR\} syntax, not op:// references directly. Use the sh -c "TAVILY_API_KEY=$(op read '...') exec npx ..." wrapper pattern to read from 1Password at startup.

Option B: Remote MCP (hosted, no npx)

Tavily offers a hosted MCP server — no local process needed. Generate the URL at https://app.tavily.com → "Remote MCP" → "Generate MCP Link":

"tavily": {
  "type": "url",
  "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=YOUR_KEY",
  "disabled": false
}

Without Tavily

Agents fall back to WebFetch (Haiku-summarized) → agent-browser (full headless). Tavily fills the middle tier with raw markdown extraction and semantic search.

MCP Dependencies

Plugin Integration

OrchestKit agents and skills integrate with these MCPs:

Without MCPs

Commands still work - MCPs just enhance them:

• /ork:implement works, but without latest library docs (context7)
• Web research works via WebFetch/WebSearch, but without raw markdown extraction (tavily)
• Session continuity works via local files and knowledge graph

Browser Automation

For browser automation and testing, use the agent-browser skill instead of an MCP. See /ork:agent-browser for Vercel's headless browser CLI.

Presets

Preset Definitions

Complete (Default)

Everything enabled - full AI-assisted development.

{
  "preset": "complete",
  "skills": {
    "ai_ml": true,
    "backend": true,
    "frontend": true,
    "testing": true,
    "security": true,
    "devops": true,
    "planning": true
  },
  "agents": {
    "product": true,
    "technical": true
  },
  "hooks": {
    "safety": true,
    "productivity": true,
    "quality_gates": true,
    "team_coordination": true,
    "notifications": false
  },
  "commands": { "enabled": true },
  "mcps": {
    "context7": false,
    "sequential_thinking": false,
    "memory": false
  }
}

Standard

All skills, no agents (spawn manually).

{
  "preset": "standard",
  "skills": { "ai_ml": true, "backend": true, "frontend": true, "testing": true, "security": true, "devops": true, "planning": true },
  "agents": { "product": false, "technical": false },
  "hooks": { "safety": true, "productivity": true, "quality_gates": true, "team_coordination": true, "notifications": false },
  "commands": { "enabled": true },
  "mcps": { "context7": false, "sequential_thinking": false, "memory": false }
}

Lite

Essential skills only, minimal overhead.

{
  "preset": "lite",
  "skills": {
    "ai_ml": false,
    "backend": false,
    "frontend": false,
    "testing": true,
    "security": true,
    "devops": false,
    "planning": true
  },
  "agents": { "product": false, "technical": false },
  "hooks": {
    "safety": true,
    "productivity": true,
    "quality_gates": false,
    "team_coordination": false,
    "notifications": false
  },
  "commands": {
    "enabled": true,
    "disabled": ["add-golden", "implement", "fix-issue", "review-pr", "run-tests", "create-pr"]
  },
  "mcps": { "context7": false, "sequential_thinking": false, "memory": false }
}

Hooks-only

Just safety guardrails, no skills or agents.

{
  "preset": "hooks-only",
  "skills": {
    "ai_ml": false,
    "backend": false,
    "frontend": false,
    "testing": false,
    "security": false,
    "devops": false,
    "planning": false
  },
  "agents": { "product": false, "technical": false },
  "hooks": {
    "safety": true,
    "productivity": true,
    "quality_gates": false,
    "team_coordination": true,
    "notifications": false
  },
  "commands": { "enabled": false },
  "mcps": { "context7": false, "sequential_thinking": false, "memory": false }
}