---
title: Configuration
description: Environment variables, MCP servers, and memory tier setup.
---

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

## Environment Variables

### Core (Auto-Detected)

| Variable | Description | Default |
|---|---|---|
| `CLAUDE_PROJECT_DIR` | Your project root | Auto-detected |
| `CLAUDE_PLUGIN_ROOT` | Plugin installation path | Auto-detected |
| `CLAUDE_SESSION_ID` | Current session UUID | Auto-generated |

### Web Research (Optional)

| Variable | Description | Effect |
|---|---|---|
| `TAVILY_API_KEY` | Tavily search API | Enables search/extract/map in web research workflow |

### Setting Variables

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

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

| Tier | Storage | Config Needed | What It Does |
|---|---|---|---|
| **1. Graph** | MCP `mcp__memory__*` | None (zero-config) | Knowledge graph: entities + relations |
| **2. Local** | `.claude/memory/*.jsonl` | None (auto-created) | Session persistence, queue sync |
| **3. CC Native** | `~/.claude/projects/*/memory/MEMORY.md` | None (auto-sync) | Injected into system prompt |

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

## MCP Servers

OrchestKit supports 10 MCP servers for web search, component registries, design extraction, and more. All are optional — skills and agents work without them.

See the full **[MCP Servers guide](/docs/foundations/mcp-servers)** for:
- All 10 MCPs organized by tier (bundled, API key required, user-installable)
- Recommended MCPs by project type (React, backend, design system, AI/LLM)
- Complete agent-to-MCP mapping (all 37 agents)
- Setup instructions, token overhead, and graceful degradation

**Quick start**: context7, memory, and sequential-thinking work with zero config. Tavily needs a free API key from [app.tavily.com](https://app.tavily.com).

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

## Keybindings

OrchestKit ships with 8 chord keybindings for the most-used skills. Press the first key combo, release, then press the second:

| Shortcut | Skill | What It Does |
|---|---|---|
| `ctrl+k ctrl+f` | `/ork:fix-issue` | Fix a GitHub issue |
| `ctrl+k ctrl+i` | `/ork:implement` | Implement a feature |
| `ctrl+k ctrl+e` | `/ork:explore` | Deep codebase exploration |
| `ctrl+k ctrl+r` | `/ork:review-pr` | Review a pull request |
| `ctrl+k ctrl+m` | `/ork:memory` | Search/load memory |
| `ctrl+k ctrl+a` | `/ork:assess` | Quality assessment |
| `ctrl+k ctrl+c` | `/ork:commit` | Conventional commit |
| `ctrl+k ctrl+h` | `/ork:help` | Skill directory |

These are defined in `settings.json` and can be customized via `/ork:configure` or by editing `src/settings/ork.settings.json`.

## Fullscreen Rendering

Claude Code v2.1.89+ ships an alternate rendering path that eliminates flicker, keeps memory flat in long conversations, and adds mouse support. Helpful in VS Code's integrated terminal, tmux, and iTerm2 where rendering throughput is the bottleneck.

Enable it once and it persists:

```bash
/tui fullscreen
```

Or set it directly in `~/.claude/settings.json`:

```json
{ "tui": "fullscreen" }
```

To disable: `/tui default`. Trade-offs (native `Cmd+f`, terminal selection) and tmux/iTerm caveats are covered in the official docs: [Fullscreen rendering](https://code.claude.com/docs/en/fullscreen).

## Status Line

OrchestKit configures a persistent status line at the bottom of your terminal showing:

```
ork v7.1.4 │ feat/my-branch │ 3 uncommitted
```

This updates automatically and shows the plugin version, current git branch, and uncommitted file count.

## Spinner Customization

### Custom Verbs

While Claude thinks, the spinner shows custom verbs: *Orchestrating*, *Coordinating*, *Synthesizing*, *Architecting*, *Dispatching*, *Producing*, *Rendering*, *Composing*.

### Spinner Tips

Between tasks, the spinner shows OrchestKit tips to help discover features:

- `/ork:memory search` to find past decisions
- `ctrl+k ctrl+f` to quick-fix an issue
- `/ork:analytics` shows usage patterns
- `/ork:explore` for deep codebase understanding
- `/ork:assess` rates code quality 0-10

Tips are additive — Claude Code's default tips still appear alongside OrchestKit's.

## 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
- Keybindings and spinner customization

## Next Steps

- **[The 3 Building Blocks](/docs/foundations/skills-agents-hooks)** — Understand the architecture
- **[Memory System](/docs/memory/overview)** — Deep dive into 3-tier memory
