---
title: "Configuration"
description: "Environment variables, MCP servers, and memory tier setup."
canonical: "https://orchestkit.yonyon.ai/docs/getting-started/configuration"
---

# Configuration

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 |

### Library Docs (Optional, Pro tier only)

| Variable | Description | Effect |
|---|---|---|
| `CONTEXT7_API_KEY` | Context7 API key, format `ctx7sk-...` | Raises the context7 quota from the free 1,000 requests to 5,000 per seat and unlocks private repo parsing |

context7 itself does **not** need this variable. The free tier works without a key.
Set it only if you hold a Context7 Pro subscription, and only alongside the matching
`Authorization` header in `.mcp.json` (see
[MCP Servers](/docs/foundations/mcp-servers#context7-library-docs)). A header that
references an unset variable is worse than no header: the server still connects and
still lists its two tools, then fails every query with
`Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix.`

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

# Context7 Pro (optional; the free tier needs no key)
export CONTEXT7_API_KEY="ctx7sk-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 but one are optional.

**context7 is a prerequisite.** 22 of the 36 agents grant `mcp__context7__*` in their
frontmatter, the plugin ships no server definition for it, and `.mcp.json` is
user-owned. An unconfigured context7 does not error: those agents fall back to
training-data answers about your libraries, silently. Add it before you rely on 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 36 agents)
- Setup instructions, token overhead, and graceful degradation

**Quick start**: memory and sequential-thinking work with zero config. context7 needs
one `.mcp.json` entry, and is the one server not to skip; the free tier (1,000 requests,
public repos) needs no API key, and a Context7 Pro key raises that to 5,000 per seat with
private repo parsing. Tavily needs a free API key from [app.tavily.com](https://app.tavily.com).

```json
"context7": { "type": "http", "url": "https://mcp.context7.com/mcp" }
```

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

Claude Code owns keybindings, and a plugin cannot ship shortcuts that invoke its skills. Run `/keybindings` to create or open your own config at `~/.claude/keybindings.json`:

```json
{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [
    { "context": "Chat", "bindings": { "ctrl+e": "chat:externalEditor" } }
  ]
}
```

Every value on the right is drawn from a **closed set of built-in `namespace:action` identifiers** — `chat:submit`, `app:toggleTodos`, `scroll:bottom`, and so on. There is no action that runs a slash command, so `"ctrl+k ctrl+c": "/ork:commit"` is not expressible: Claude Code validates the file on load and reports invalid entries in the debug log (`claude --debug`).

Earlier versions of this page advertised 8 `ctrl+k` chords bound to OrchestKit skills, and described `src/settings/ork.settings.json` as the place to customize them. Both were wrong. Claude Code reads only a small set of keys from a plugin `settings.json`, keybindings has never been one of them, and no keybinding of any kind can target a skill. The chords never fired.

The fast path to a skill is typing `/ork:` and letting autocomplete narrow it. Keybindings are still worth setting for Claude Code's own controls — the full context and action tables are in the [Claude Code keybindings docs](https://code.claude.com/docs/en/keybindings).

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