Configuration

OrchestKit works out of the box with zero configuration. This page covers optional settings for power users.

Environment Variables

Core (Auto-Detected)

Web Research (Optional)

Setting Variables

Add to your shell profile (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish):

# Web Research
export TAVILY_API_KEY="tvly-your-key-here"

Then restart Claude Code or open a new terminal.

Memory Tiers

OrchestKit has 3 memory tiers. All work automatically with zero configuration:

High-confidence decisions (confidence >= 0.7) automatically promote from Graph to CC Native, ensuring they persist even without OrchestKit installed.

MCP Servers

OrchestKit ships with 4 MCPs enabled by default in .mcp.json:

Tavily Setup

Tavily requires a free API key (app.tavily.com — 1,000 credits/month free).

Option A — 1Password (recommended):

op item create --category "API Credential" --title "Tavily API Key" "API Key=tvly-..."

The .mcp.json entry uses op read to fetch it at startup — no key in config files.

Option B — environment variable:

export TAVILY_API_KEY="tvly-your-key-here"

Then update .mcp.json to use "${TAVILY_API_KEY}" in the env block.

Option C — Remote MCP (no local process):

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

Disabling an MCP

Set "disabled": true for any MCP in .mcp.json:

"sequential-thinking": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
  "disabled": true
}

Without MCPs

All skills and agents work without MCPs — they add extra capabilities:

• Without context7: /implement works but won't fetch latest library docs
• Without tavily: web research falls back to WebFetch → agent-browser
• Without memory: decisions persist via local files and CC Native memory

Hook Behavior

Hooks fire automatically. If a hook blocks an action unexpectedly:

1. Check which hook blocked: the error message includes the hook name
2. Hooks you can customize:
   • file-guard: Protected file paths and file size limits (override with ORCHESTKIT_MAX_FILE_LINES / ORCHESTKIT_MAX_TEST_FILE_LINES env vars)
   • dangerous-command-blocker: Blocked commands list
   • permission auto-approve: Safe command patterns

Most users never need to customize hooks. They're designed to be transparent.

Plugin Settings

Run /ork:configure to adjust:

• Notification preferences (desktop alerts, sounds)
• Memory sync frequency
• Hook toggle system (enable/disable specific hooks)
• Agent model preferences

Next Steps

• The 3 Building Blocks — Understand the architecture
• Memory System — Deep dive into 3-tier memory