[ xen // quickstart ]

Quickstart

Install xen, add it to Claude Code, configure your provider key, and make your first multi-model council call.

[ 01 // before you start ]

Before you start

Terminal — environment verificationpre-flight

which claude && claude --version

# the path to claude, then its version, such as 2.1.309 (Claude Code)

uname -s -m

Linux x86_64

Make sure your environment meets these three requirements before running the install command:

  1. Claude Code installed: The installer requires Claude Code (claude) on your PATH. If Claude Code is missing, the installer stops and asks you to install it first. The installer sets up Claude Code only at v1; other MCP clients are not configured by the installer.
  2. Linux or WSL: xen runs on Linux, or on Windows through Windows Subsystem for Linux (WSL). If you are on Windows, run the installer inside your WSL distribution. Claude Code must be installed inside that Linux distro; a Windows claude.exe accessed across /mnt/ is refused. Native Windows installation is planned for v1.1.
  3. One provider API key: You need an API key from at least one model provider. OpenRouter is suggested ("one key reaches the most models", the installer's own wording), as one key gives your agent access to Claude, Gemini, GPT, DeepSeek, Grok, and more.

Where to get an API key

Key security

The key sits in a file on your machine that only you can read (~/.config/xen/xen.env, mode 0600) and goes only to the provider you chose.

[ 02 // install ]

Install

Run this one command in your terminal to download xen, configure your key, and register the server with Claude Code:

Terminal

curl -fsSL https://get.xenmcp.dev/install.sh | bash

To inspect what will happen before anything is downloaded or written, run the dry-run form:

Terminal (dry run)

curl -fsSL https://get.xenmcp.dev/install.sh | bash -s -- --dry-run

What the installer does

  • Checks that Claude Code is present on your PATH.
  • Downloads the xen binary, checks it against the release's SHA-256 checksums, and puts it in ~/.local/bin/xen. The checksums come from the same server, so they catch a corrupted download; the release's signature is checked from the first update on.
  • Runs xen setup, which asks which provider you want to use and prompts for your API key.
  • Writes the key securely to ~/.config/xen/xen.env with mode 0600 (readable only by your user).
  • Installs the xen plugin and registers xen's six skills with Claude Code.

Note on key entry at v1

The key is shown as you type at v1 (paste it while nobody can see your screen). Masked password input is planned for a v1.0.x release.

After the install finishes: restart Claude Code, or run /mcp in a running session, to start using xen.

[ 03 // try it ]

Try it

Step 1: Confirm the connection

In Claude Code, ask xen to list available models. This calls xen's listmodels tool, costs zero tokens, and confirms the MCP server answers:

Claude Code prompt
> Ask xen to list available models

Step 2: Run your first council call

Once models are listed, test multi-model orchestration with a council debate. Ask for it in plain words; the phrase "convene the council" loads xen's council skill:

Claude Code prompt
> Convene the council with xen: should we put Redis in front of Postgres as a read cache?

xen convenes three seats across your available frontier models—arguing for, against, and evaluating trade-offs from a neutral stance—then synthesizes a single structured verdict:

Council debate · session outputcaptured session · council output 2026-09-24
Council status: council_complete

for (glm-5.2):

Yes, deploying Redis as a read cache in front of Postgres is a sound architectural decision for this workload—hot read queries dominating traffic is the textbook case for an external cache...

against (gemini-3.1-pro-preview):

Introducing Redis is an expensive and premature architectural leap that injects substantial operational complexity and cache-invalidation risks before exhausting native Postgres optimization...

neutral (grok-4.7):

A Redis read cache in front of Postgres is a sound pattern only after measurement shows the database is the bottleneck and simpler Postgres-side fixes are exhausted...

synthesis (gpt-6-astra):

Do not commit to Redis yet. Approve a measured, narrowly scoped evaluation—not a default architectural rollout. Proceed only if the pilot delivers a worthwhile measured improvement.

[ 04 // change your key ]

Change your key or provider

To change your API key or switch to another provider, re-run xen setup in your terminal:

Terminal
xen setup

Setup checks your current ~/.config/xen/xen.env, identifies which key is already configured (for example, OPENROUTER_API_KEY, never revealing the secret value), and asks whether you want to keep or replace it.

Self-hosted endpoints (Ollama, vLLM, LM Studio)

To configure a local OpenAI-compatible endpoint, edit ~/.config/xen/xen.env directly and add your endpoint URL:

# ~/.config/xen/xen.env

CUSTOM_API_URL=http://localhost:11434/v1

CUSTOM_API_KEY=optional-local-token

After editing, restart Claude Code or run /mcp in your Claude session.

[ 05 // update and uninstall ]

Update and uninstall

Updating xen

xen is manual: it never checks for updates or phones home on its own. To update to the latest release, run:

Terminal
xen update

xen update checks the latest published release, verifies the cryptographic signature (SHA256SUMS.sig), replaces the binary atomically, updates the license files, and refreshes the Claude Code plugin registration.

To test the update without writing anything, pass --dry-run:

Terminal (dry run)
xen update --dry-run

If your installation is already up to date, it prints:xen v1.0.0 is up to date (the latest release is v1.0.0).

Upgrading from v0.6.0

Run xen update, then restart Claude Code or run /mcp. Four changes can affect you:

  • Three tools have new names: thinkdeep is now deepthink, apilookup is now docslookup, and tracer is now trace. A call to an old name answers "Unknown tool" and names the new one. If you wrote permission rules for single tools (for example mcp__plugin_xen_xen__thinkdeep), add the new names; a rule for all of xen's tools (mcp__plugin_xen_xen__*) needs no change.
  • One setting has a new name: XEN_DEFAULT_THINKING_MODE_THINKDEEP is now XEN_DEFAULT_THINKING_MODE_DEEPTHINK, and the old name is no longer read. The installer never sets it, so this matters only if you set it yourself.
  • consensus no longer reports consensus_confidence: it always said "high". It now lists models_without_answer: each model that failed, or only asked for files instead of answering.
  • A model that only asks for files is reported as such: chat answers with status files_required_to_continue and the model's request, instead of passing it off as an ordinary answer.

Uninstalling xen

To remove xen and deregister it from Claude Code, run:

Terminal
xen uninstall

By default, uninstall removes the Claude Code plugin and deletes the binary, but asks whether to delete ~/.config/xen/xen.env so you do not lose your key by accident. Pass --yes to remove the env file without prompting.

Running xen uninstall --dry-run lists exactly what would be removed without changing anything:

Dry run: nothing will be removed and no command will run.

Would run: claude plugin uninstall xen@xen-install

Would run: claude plugin marketplace remove xen-install

Would remove ~/.local/share/xen/plugin if it holds xen's plugin, and the license files in ~/.local/share/xen.

Would ask before removing ~/.config/xen/xen.env (your provider key), or keep it if there is no terminal; --yes removes it without asking.

Would remove ~/.local/bin/xen.

[ 06 // configuration ]

Configuration reference

xen reads its configuration from ~/.config/xen/xen.env (or real environment variables). Twelve variables configure the server, alongside the provider key variables:

Web search is on by default. A model that supports it can look things up on the web during a chat, deepthink, consensus or council call, and its provider bills each search on top of the tokens. If you attach private code, turn search off with XEN_WEB_SEARCH=off.

Provider key variables

Stored in ~/.config/xen/xen.env. You need only one hosted key to start.

OPENROUTER_API_KEYdefault: unset

API key for OpenRouter (suggested: one key reaches Claude, Gemini, GPT, DeepSeek, Grok, and more).

ANTHROPIC_API_KEYdefault: unset

Direct API key for Anthropic (Claude models).

GEMINI_API_KEYdefault: unset

Direct API key for Google Gemini models.

OPENAI_API_KEYdefault: unset

Direct API key for OpenAI (GPT models).

XAI_API_KEYdefault: unset

Direct API key for xAI (Grok models).

ZAI_API_KEYdefault: unset

Direct API key for Z.ai (GLM models).

MOONSHOT_API_KEYdefault: unset

Direct API key for Moonshot AI (Kimi models), from the international platform (platform.kimi.ai).

CUSTOM_API_URLdefault: unset

Base URL for self-hosted OpenAI-compatible endpoint (e.g. http://localhost:11434/v1 for Ollama).

CUSTOM_API_KEYdefault: unset

Optional authorization token for self-hosted OpenAI-compatible endpoint.

Server configuration variables

Optional server settings. These can be set in ~/.config/xen/xen.env or passed as environment variables.

XEN_WORKSPACE_ROOTdefault: CLAUDE_PROJECT_DIR, else home

The file-access boundary. Every file path attached to a call is checked against this directory before anything is read. When unset, xen uses CLAUDE_PROJECT_DIR (set by Claude Code to the project you opened); if unset, falls back to your home directory. Relative paths and symlinks are resolved within this root.

XEN_DISABLED_TOOLSdefault: empty

Comma-separated tool names to omit from tools/list (e.g. XEN_DISABLED_TOOLS=secaudit). version and listmodels cannot be disabled.

XEN_MAX_TOOL_SCHEMA_TOKENSdefault: unset (no budget)

Token budget for advertised tool schemas. tools/list admits tools in fixed priority order until the budget is spent, always including version and listmodels.

XEN_DEFAULT_MODELdefault: auto

Default model when a request names none. auto resolves per call to the preferred model for that tool category.

XEN_LOG_LEVELdefault: info

Verbosity written to stderr: debug, info, warn (or warning), error. Unrecognised values fall back to info.

XEN_LOCALEdefault: unset

When set (e.g. fr-FR), system prompts instruct models to respond in that locale.

XEN_WEB_SEARCHdefault: on

Web search for chat, deepthink, consensus and council on the models that support it (listmodels shows "Web search: yes"). The model decides when to search, through its provider's own search, up to three times per request. Each search is billed by that provider, the query goes to its search engine, and the contents of an attached file can reach a model that searches. off, false, 0 or no (any case) turn it off; anything else, or unset, leaves it on. Restart Claude Code or run /mcp after changing it.

XEN_PERSISTENT_MEMORYdefault: false

Enables conversation thread persistence on disk. Must be the word true (case-insensitive).

XEN_MEMORY_DIRdefault: $XDG_STATE_HOME/xen/memory

Directory where persisted conversation threads are stored.

XEN_CONVERSATION_TIMEOUT_HOURSdefault: 3

Lifetime in hours for conversation threads before expiry.

XEN_MAX_CONVERSATION_TURNSdefault: 50

Maximum number of turns a single conversation thread can retain.

XEN_DEFAULT_THINKING_MODE_DEEPTHINKdefault: high

Printed in the startup banner only. deepthink expert calls use high regardless of this setting.

[ 07 // troubleshooting ]

Troubleshooting

1. A tool answers that xen has no provider API key

xen starts without an API key and allows client handshake tools (such as version and listmodels) to run. When a tool calls a model without a configured key, it returns:

xen has no provider API key configured, so this tool cannot call a model. Run `xen setup` in a terminal to add one (an OpenRouter key is suggested: one key reaches the most models), or add a provider key such as OPENROUTER_API_KEY to the env file ~/.config/xen/xen.env yourself; then restart Claude Code or run /mcp.

Fix: Run xen setup in your terminal to enter your key, or add a key to ~/.config/xen/xen.env, then run /mcp in Claude Code.

2. Setup stops: a xen server is already registered

If xen was previously registered by hand with claude mcp add, setup stops to prevent two instances loading at once:

a xen server is already registered with `claude mcp add`; installing the plugin would load two. Remove it with `claude mcp remove xen`, or pass --force

Fix: Run claude mcp remove xen in your terminal, then run the installer or xen setup again.

3. `xen: command not found` when running by hand

If running xen directly in your shell reports command not found, ~/.local/bin is not on your shell's PATH. The installer warns:

Note: ~/.local/bin is not on your PATH. Add this to your shell profile to run xen by hand: export PATH="$HOME/.local/bin:$PATH"

Fix: Add export PATH="$HOME/.local/bin:$PATH" to your ~/.bashrc or ~/.zshrc. Claude Code itself is unaffected, as the plugin registers the binary with its full absolute path.

4. Under WSL, the installer stops over `claude`

If the installer finds Windows Claude Code via the Windows PATH instead of a native Linux install, it stops:

'claude' resolves to a Windows program (/mnt/c/...). Install Claude Code inside this Linux distro, then run this again.

Fix: Install Claude Code inside your Linux/WSL distribution, following Claude Code's own setup instructions from your WSL shell, so that which claude names a Linux path.

5. xen cannot read an attached file

xen enforces strict workspace containment. If an attached file sits outside the active workspace directory, xen refuses to read it:

--- ERROR ACCESSING FILE: /path/to/file ---
/path/to/file is outside the workspace root; send a file within it

Fix: Make sure attached files sit within the project folder you opened in Claude Code (CLAUDE_PROJECT_DIR), or set XEN_WORKSPACE_ROOT in ~/.config/xen/xen.env to expand the allowed directory boundary.

[ 08 // known issues ]

Known issues

These issues are known, understood, and accepted for v1.0.0. None of them sends a file's contents anywhere it should not go. Each is tracked for a later release.

File-boundary issues on your machine

The following four issues concern files on your own machine. All four require someone who can already influence what xen is asked to do, or who can already write files inside the folders xen may read. xen only reads inside the folders it is allowed to use (your project, by default):

XG-144

A continued conversation can reveal whether a file exists

When a conversation continues, xen re-checks the size of files that earlier turns attached before it applies its folder rules. A file xen would refuse to read still changes the note the model receives (an error note rather than an "omitted" note), so the model can tell whether that file exists. Its contents are never read or sent.

XG-145

An image refusal can reveal whether an image file exists, and its size

xen checks the size of attached images before it applies its folder rules, so the "too many or too large images" answer can reflect an image outside the allowed folders. The image itself is never read or sent.

XG-147, XG-164

A file swapped at the wrong moment

If someone who can write inside the allowed folders swaps a file in the instant between xen checking it and reading it, xen can read the swapped-in file instead (for images), or a read can hang (if the file is replaced by a special "pipe" file). A hang lasts until you restart Claude Code or run /mcp.

Cost and polish issues

XG-146

No total size limit for images on consensus and workflow tools

Each image is limited to 20 MB, but there is no limit on the total, and consensus sends the images to every model it asks. Many large images make large requests, and your provider bills for them. Attach only the images a question needs.

XG-235

Some provider errors show raw error text

When a provider rejects a request, part of the message can appear in an unpolished form, for example Error code: 400 - { 'error': { 'code': 400, 'message': 'Bad model name' } }. The information is correct; formatting polish is scheduled for a v1.0.x release.

[ 09 // tools catalog ]

Explore xen's tools

xen packages sixteen specialized tools and six skills into your agent, from multi-model consensus and deep code analysis to precision tracing and debate.

View tools index