`README.md`

65 lines

# Exo helper for Claude Code and Codex

Two shared MCP tools use the existing local Exo service directly:

- `exo_status`: reports live nodes and actual readiness of both model options.
- `ask_exo`: summarizes supplied text, extracts fields, drafts small suggestions, or performs preliminary review. The calling coding agent must verify the answer.

Default model: `mlx-community/Qwen3-VL-4B-Instruct-4bit`, cached on the M3 Ultra. It runs on that one node; three connected cluster nodes do not mean this helper is distributing computation across all three.

Selectable DeepSeek option: `mlx-community/DeepSeek-R1-0528-Qwen3-8B-4bit`, approximately 4.3 GiB on disk. This is the compact DeepSeek R1-0528 distillation based on Qwen3-8B, quantized by MLX Community; it is not the full-size DeepSeek model. [DeepSeek model card](https://huggingface.co/deepseek-ai/DeepSeek-R1-0528-Qwen3-8B), [MLX conversion](https://huggingface.co/mlx-community/DeepSeek-R1-0528-Qwen3-8B-4bit).

The bridge uses stdio, so each coding app starts it when needed. It has no listening port, filesystem tools, shell execution, or model-management tools. Requests go to `http://127.0.0.1:52415`; no Ollama runtime or paid fallback is used. Existing primary providers stay in place.

## Use

In a new Claude Code or Codex session, ask:

> Check exo_status, then use ask_exo to summarize this text. Review its answer before using it.

To select DeepSeek, say:

> Use DeepSeek through Exo to review this code.

The coding agent calls `ask_exo` with `model: "deepseek"`. `model: "qwen"` chooses the original helper; omitting `model` preserves the configured default. `exo_status` accepts the same optional selection. Both tools list only these explicit options. Selecting an unavailable model returns an error without switching to the other model.

Supply relevant text or code via `context`. The helper cannot read a filename. Keep tasks narrow and verify the results of these small local models.

Combined prompt/context limit: 16,000 characters. Output defaults to 512 tokens for Qwen and 1,024 for DeepSeek; the maximum is 1,024, including reasoning tokens. DeepSeek can spend part of this allowance reasoning and may need a larger limit for a complex task. A response ending at the token limit is marked `truncated`. Each bridge process handles at most one inference request at a time; independent client processes share Exo's own scheduling. An unavailable/busy model returns an explicit error. Requests are never automatically retried or rerouted.

## Installation

```sh
npm ci --ignore-scripts
codex mcp add exo-helper --env EXO_TIMEOUT_MS=45000 -- /opt/homebrew/bin/node /Users/macstudio3/Projects/exo-helper/server.mjs
claude mcp add exo-helper --scope user -e EXO_TIMEOUT_MS=45000 -- /opt/homebrew/bin/node /Users/macstudio3/Projects/exo-helper/server.mjs
```

Both registrations set a 45-second inference deadline to fit the clients' tool timeouts. The preflight has its own eight-second deadline. Neither setting changes the primary model.

After registration, new sessions load the helper. In an existing Claude Code session, use `/mcp` to reconnect; restart the session if the new server is absent. Start a new Codex session to load its new MCP configuration.

## Prerequisite and recovery

Exo must already be running with the configured model loaded and every assigned runner ready. Open `http://localhost:52415` to manage the model. The bridge does not load or download models on demand.

`EXO_MODEL` selects the default model, and `EXO_BASE_URL` can select a different loopback port. Only loopback HTTP origins are accepted. A request may select the allowlisted Qwen or DeepSeek model but cannot change the endpoint or environment configuration. `EXO_TIMEOUT_MS` defaults to 90,000 and is capped at 180,000.

## Verification

```sh
npm test
npm run verify
```

The integration check starts real SDK MCP clients, discovers tools, checks live model readiness, and sends arithmetic and text-extraction tasks to Exo. It also verifies oversized input, an unloaded model, and an unreachable backend. Evidence: `verification/integration.json` and `verification/e2e-proof.json`.

## Remove the integration

```sh
codex mcp remove exo-helper
claude mcp remove --scope user exo-helper
```

Removing MCP registration does not stop Exo or remove downloaded models. The model loaded during setup is intentionally retained for use. Private configuration backups from TK-11320 are stored in the ignored `verification/private/` directory; restore only the helper entry if other settings have since changed.