Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
MCP Server Mode
Use any claudish model as a tool inside Claude Code.
Claudish isn't just a CLI. It's also an MCP server that exposes external AI models as tools.
Claude can call Grok, GPT-5, or Gemini mid-conversation to get a second opinion, or delegate a task to another model as a full async session that it polls and answers with send_input.
The server exposes 15 tools across four groups: low-level (3), agentic (3), session (8), and debug (1).
Requirements for team and sessions
Every team slot and every create_session session is a real, interactive Claude Code session
running your model, inside its own headless magmux pane. That needs:
- magmux 0.18.0 or newer. It is bundled with the npm package on macOS and Linux; otherwise
install it with
brew install MadAppGang/tap/magmux. Without it,team(mode:"run"),create_sessionand the CLI'sclaudish team/--teamrefuse withError: magmux_unavailable: …instead of falling back to anything else. - macOS or Linux. Windows is not supported for MCP
team,create_session, or the CLI'sclaudish team/--team. The other tools work everywhere. - At most 48 live panes per user, across every claudish process; past that a new run or session is
refused with
Error: pane_limit: ….
Quick Setup
1. Add to your Claude Code MCP settings:
{
"mcpServers": {
"claudish": {
"command": "claudish",
"args": ["--mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
}
}
}
}
2. Restart Claude Code
3. Use it:
Ask Grok to review this function
Claude will use the run_prompt tool to call Grok.
Available Tools
run_prompt
One quick prompt, straight to one model's API: a single request and its answer. No Claude Code
session, no tools, no files, no conversation state — this is not subagent work. For a task that
needs tools, files or more than one turn, use create_session (one model) or team (several
models). Non-Claude models (Kimi, GLM, Qwen, MiniMax, Gemini, GPT, Grok, …) go through claudish's
routing straight to the provider's API.
Parameters:
model(required) - Model name or model spec. A bare name auto-routes to the best provider (e.g.,kimi-k3,glm-5.3);provider@modelpins the provider (e.g.,google@gemini-4-argon,or@x-ai/grok-4.7).prompt(required) - The prompt to sendsystem_prompt(optional) - System prompt for contextuser_required_provider(optional) -truewhen you, the user, named the provider: theprovider@modelspec is sent as given. Without it, aprovider@on a cloud catalog model is removed so claudish routing picks the provider from your setup; the answer names what was removed. Local providers, custom URLs and chains are never changedeffort(optional) - Reasoning effort for this request (none…max). Take it from thelist_modelseffort table;defaultkeeps Claude Code's own. Omitted while the model has a row in the table, nothing runs and the answer isneeds_effort:with that row. Sent asoutput_config.effortand mapped onto the levels the model's connection publishes; ignored for a bare Claude name
There is no output-limit parameter. The request carries no max_tokens, so the provider applies
its own default.
Claude models. A bare Claude name (claude-*, opus, sonnet, haiku, internal) does not
go to an API from the MCP server. It runs as one Claude Code print-mode call through claudish
(claudish -p --model <model> --output-format json …) on your own Claude Code login: tools, MCP
servers, settings sources and slash commands are off, Claude Code's default system prompt is
replaced by yours (or by an empty one), and it runs in a new empty working directory so no
project CLAUDE.md or memory is loaded. claudish never reads your Claude Code login itself; the
claude binary signs in on its own. The answer ends with an Auth: line,
Auth: Claude Code login (subscription) on a subscription. If you never signed in, the error is
Claude Code's own "Not logged in" text: run claude once. An explicit spec such as
anthropic@claude-opus-5-5 is the metered Anthropic API and takes the ordinary routing path.
Model IDs:
| Common Name | Model ID |
|---|---|
| Grok | x-ai/grok-code-fast-1 |
| GPT-5 Codex | openai/gpt-5.1-codex |
| Gemini 3 Pro | google/gemini-3-pro-preview |
| MiniMax M2 | minimax/minimax-m2 |
| GLM 4.6 | z-ai/glm-4.6 |
| Qwen3 VL | qwen/qwen3-vl-235b-a22b-instruct |
Example usage:
Ask Grok to review this function
→ run_prompt(model: "x-ai/grok-code-fast-1", prompt: "Review this function...")
Use GPT-5 Codex to explain the error
→ run_prompt(model: "openai/gpt-5.1-codex", prompt: "Explain this error...")
Tip: Use list_models first to see all available models with pricing.
list_models
List recommended models with pricing and capabilities.
Parameters: None
Returns: Table of curated models with:
- Model ID
- Provider
- Pricing (per 1M tokens)
- Context window
- Capabilities (Tools, Reasoning, Vision)
After the models, a Recommended effort by task type table from the cloud models catalog: a
row per model, a column per task type (planning, implementation, code_review, …). The
calling agent picks the column for its task and passes each model's cell as team efforts or
create_session / run_prompt effort. claudish never guesses the task type itself.
search_models
Search all OpenRouter models.
Parameters:
query(required) - Search term (name, provider, capability)limit(optional) - Max results (default: 10)
Example:
Search for models with "vision" capability
compare_models (debug)
A debug tool, in the debug group. Send the same single prompt to several models, one after
another, and show their answers side by side — to check that routes answer or to eyeball raw
answers. Each model gets exactly what run_prompt sends: one request, no tools, no Claude Code
session (a Claude entry takes run_prompt's Claude Code path). Not for real work: use team for
a blind-judged multi-model run, or create_session for one model doing a task.
Parameters:
models(required) - Array of model names or model specs, in the order to run themprompt(required) - The prompt to comparesystem_prompt(optional) - System prompt
Example:
Check that kimi-k3, glm-5.3 and minimax-m3 all answer: "Say OK"
preflight
Diagnostic: for a list of models, report which provider would serve each, whether that hop is
subscription or metered, and whether it is reachable now. It is not a step before team,
create_session or run_prompt; they resolve their own routing.
team
Run AI models on a task with anonymized outputs and optional blind judging. Each slot is an interactive Claude Code session in its own headless magmux pane (see "Requirements" above).
Parameters:
mode(required) - One of:run,status,list,capture,cancel,resize,judge,run-and-judgepath- Session directory path (must be within current working directory). Required by every mode exceptlistmodels- Model IDs to run (required forrunandrun-and-judge). Native Claude names (opus,sonnet,haiku,internal) are runnable slots toouser_required_provider- Themodels/judgesentries whose provider you, the user, named, exactly as written there. Aprovider@on a cloud catalog model is removed so claudish routing picks the provider from your setup; the answer names what was removed. Local providers, custom URLs and chains are never changedefforts- Reasoning effort per model, e.g.{"gpt-6-luna": "high", "kimi-k3": "max"}. Keys must match amodelsentry exactly. Take each level from thelist_modelseffort table. The slot pins it on every request (--effort-override); a model without an entry keeps Claude Code's own effort. Omitted while a model has a row, nothing starts and the answer isneeds_effort:with the rows;{}keeps Claude Code's own effort for every modeljudges- Model IDs to use as judges (default: same as runners)input_file- Path to a file holding the task prompt (preferred for anything longer than a sentence)input- Task prompt as inline text. If neither is given, aninput.mdalready in the session directory is usedrequire_pattern- Regex (no flags) each slot's answer must match, or the slot is EMPTYshape_mismatch. Recommended whenever your prompt mandates an output shape, e.g.```votemin_output_bytes- Report a slot EMPTY when its answer is shorter than this (default 0 = off)agent- Claude Code subagent every slot runs as (e.g.dev:reviewer); an unknown agent fails the slotagent_rejectedclaude_flags- Other Claude Code flags and their values, space-separated, never positional text (write--allowedTools Read,Bash; a value after a Claude Code switch, as in--brief now, would be the session's first prompt and is refused). Flags that would break the interactive pane (-p,--output-format,--resume, …) and print-mode-only flags (--max-turns,--max-budget-usd, …) are refusedslot- Forcaptureandresize(required) andcancel(omit to stop the whole run): the anonymised slot idrun_id- Forstatus,capture,cancelandresize: therun_idarunanswer returned; addresses that run even after a newer run reused the path. Omit it for the newest run atpathsince_seq,spans- Forcapture: seecapture_sessioncols,rows- Forresize(required): seeresize_session
Modes:
| Mode | What it does |
|---|---|
run |
Start the models and return once every slot has taken its prompt (at most about two minutes, usually seconds) — it does not wait for answers. Outputs are written anonymized to the session directory. The result carries run_id and monitor_record, the run's record under ~/.claudish/sessions/ (see "Session records on disk") |
status |
Progress of a run: per-slot rows under run.slots (state, reason, reason_detail, tokens, idle seconds, activity), plus contract_version and capabilities |
list |
Every run this server holds: {contract_version, capabilities, runs}. Finished runs stay listed for 30 minutes |
capture |
One slot's current terminal screen (same shape as capture_session) |
cancel |
Stop one slot (slot) or every slot of the run; answers each slot's {state, changed} |
resize |
Set one slot's terminal size; answers {run_id, path, slot, cols, rows, changed, seq, pending?} (same rules as resize_session) |
judge |
Blind-vote on existing outputs in the session directory |
run-and-judge |
Full pipeline: run models, then judge the outputs; holds the call open for the whole run |
No slot is ever stopped on a timer once its prompt is accepted. A slot inside a long build or test
suite can be silent for minutes and still be working; read idle_seconds and activity, and use
cancel if you decide a slot is stuck. A slot that stops on a question or a permission dialog it
cannot answer is FAILED blocked, with the question in its detail. A path holds at most one active
run.
Example:
Use team run-and-judge with Grok and GPT-5 on this architecture decision
→ team(mode: "run-and-judge", path: "./team-session", models: ["x-ai/grok-3", "openai/gpt-5.1-codex"], input: "Which approach is better: A or B?")
report_error
Report a claudish error to developers. Always ask the user for consent before calling. All data is sanitized: API keys, user paths, and emails are stripped before sending.
Parameters:
error_type(required) - One of:provider_failure,team_failure,stream_error,adapter_error,othermodel(optional) - Model ID that failedcommand(optional) - Command that was runstderr_snippet(optional) - First 500 chars of stderr outputexit_code(optional) - Process exit codeerror_log_path(optional) - Path to full error log filesession_path(optional) - Path to team session directoryadditional_context(optional) - Extra context about the errorauto_send(optional) - If true, suggest the user enable automatic error reporting
Sessions
create_session starts an external model session asynchronously. Each session is an interactive
Claude Code running your model in its own headless magmux pane (see "Requirements" above).
Nothing is pushed to you while it runs: poll list_sessions. When a session asks a question,
answer it with send_input. When it completes, get_output returns the full response.
The session tools are in the session group, which all (the default) includes:
{
"mcpServers": {
"claudish": {
"command": "claudish",
"args": ["--mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-...",
"CLAUDISH_MCP_TOOLS": "all"
}
}
}
}
CLAUDISH_MCP_TOOLS selects the tools the server lists:
CLAUDISH_MCP_TOOLS |
Tools |
|---|---|
unset, all |
all 15 |
low-level |
run_prompt, list_models, search_models |
agentic |
preflight, team, report_error |
session |
create_session, send_input, get_output, cancel_session, list_sessions, get_diagnostics, capture_session, resize_session |
debug |
compare_models |
| any other value | all 15, with a warning on stderr |
Inside a session that claudish itself started (a create_session or team pane), the server runs in nested mode. Whatever CLAUDISH_MCP_TOOLS says, it offers at most the four one-shot tools (run_prompt, compare_models, list_models, search_models) and no session tools. A model-running claudish launched from that session's shell (-p, interactive, team run) exits 64 with nested session refused. One level of nesting is the limit.
Any other value still selects all 15 tools, and the server writes one line to stderr naming the value and the valid ones:
[claudish] CLAUDISH_MCP_TOOLS="agentc" is not a tool mode; selecting all tools. Valid values: all, low-level, agentic, session, debug
channel was the old name of the session group. It is no longer a group, so it selects all 15
tools, and the warning says it was renamed to session.
Polling workflow
create_sessionreturns{session_id, state: "STARTING"}at once while Claude Code boots.- Poll
list_sessions(include_completed: true) about once every 10 seconds. Each row hasstate,activity,idle_secondsand accounting:STARTING: booting, or the first prompt is not yet accepted.RUNNING: a turn is in progress (activitynames the tool in use).AWAITING_INPUT: waiting forsend_input— an interactive session between turns, or a turn stopped on a question (activityAskUserQuestion). A send declines a question and becomes the next prompt.AWAITING_PERMISSION: a permission or plan-approval dialog is open (only when yourclaude_flagsask for one, e.g.--permission-mode plan). A send declines it and becomes the next prompt.COMPLETED,FAILED,TIMEOUT,CANCELLED,EMPTY: finished.
send_inputmay be called at any time; it is queued until the session is idle.COMPLETED: callget_outputfor the answer.FAILEDorTIMEOUT— orCOMPLETEDwith an empty or surprising answer — callget_diagnostics. It returns the child's final screen, the upstream error bodies, the recent state records, the resolved model chain and the paths to the full records. It needs no re-run and no debug flag.capture_sessionreads a session's current screen;cancel_sessionstops it. Nothing stops a session for being idle: a child inside a long build is silent and working.
One-shot — a prompt is given, so the session ends on its own after its answer:
1. create_session(model: "[email protected]", prompt: "Refactor this module")
→ { session_id: "1a2b3c4d", state: "STARTING" }
2. list_sessions(include_completed: true) every ~10 s
→ state RUNNING, activity "Read" … then state COMPLETED
3. get_output(session_id: "1a2b3c4d")
→ { output: "...", state: "COMPLETED", turnsCompleted: 1, ... }
Interactive — no prompt, so the session waits for input once Claude Code has booted and after
every turn, until you cancel it or it times out:
1. create_session(model: "[email protected]")
→ { session_id: "5e6f7a8b", state: "STARTING" }
2. list_sessions → state AWAITING_INPUT
3. send_input(session_id: "5e6f7a8b", text: "Refactor this module")
→ { success: true, queued: 0 }
4. list_sessions → RUNNING … then AWAITING_INPUT again
5. get_output(session_id: "5e6f7a8b"), then send_input again or cancel_session
create_session
Start an async session on any model: an interactive Claude Code running the model in its own
headless magmux pane. With a prompt it is one-shot and ends when that turn settles; without one it
is interactive and waits for send_input.
Parameters:
model(required) - Model identifier (e.g.,[email protected],x-ai/grok-code-fast-1)prompt(optional) - Initial prompt. If omitted, send later viasend_input.timeout_seconds(optional) - Session timeout in whole seconds, 1-3600 (default: 600). A fractional value is rounded and an out-of-range one clamped, sospawn.jsonalways carries an integer in that rangeagent(optional) - Claude Code subagent the session runs as, e.g.dev:reviewerclaude_flags(optional) - Other Claude Code / claudish flags and their values, space-separated, never positional text (write--allowedTools Read,Bash; a value after a Claude Code switch, as in--brief now, would be the session's first prompt and is refused). Flags the pane owns (-p,--resume,--model, …) and print-mode-only flags (--max-turns,--max-budget-usd, …) are refuseduser_required_provider(optional) -truewhen you, the user, named the provider. Aprovider@on a cloud catalog model is removed so claudish routing picks the provider from your setup; the answer names what was removed. Local providers, custom URLs and chains are never changedeffort(optional) - Reasoning effort for the whole session, from thelist_modelseffort table. Pinned on every request (--effort-override), over one inclaude_flags.defaultkeeps Claude Code's own; omitted while the model has a row, nothing starts and the answer isneeds_effort:work_dir(optional) - Working directory for the session (default: current directory)setup_from(optional) - Directory whose.claude/settings.jsonandsettings.local.jsonthe session inherits, so a session in anotherwork_dirkeeps your project's plugins and agents. Default: your project directory, whenwork_dirdiffers from it.nullkeeps the session onwork_dir's own settings only
Returns: { session_id: "...", state: "STARTING" } as soon as the pane exists; Claude Code then boots in it.
send_input
Send a prompt to a session. Accepted in every state that has not ended, and queued until the
session is idle: during STARTING and RUNNING it waits its turn; in AWAITING_INPUT it is
delivered at once; during a question or a permission dialog the dialog is declined and the text
becomes the next prompt. Any accepted send makes a one-shot session interactive. /clear and
/resume are not accepted.
Parameters:
session_id(required) - Session ID fromcreate_sessiontext(required) - Text to send
Returns: { success: true, queued: <n> }, or { success: false, reason, state } with reason one of terminal, delivery_unavailable, unsupported_command, unknown_session.
get_output
Retrieve a session's answer prose: each settled turn's assistant text, read from Claude Code's
own transcript. Call once list_sessions shows the session COMPLETED (or between turns of an
interactive session).
Parameters:
session_id(required) - Session ID fromcreate_sessiontail_lines(optional) - Number of lines from the end (default: all)
Returns: { sessionId, state, output, totalLines, turnsCompleted, tokensIn, tokensOut, elapsedSeconds, idleSeconds }.
cancel_session
Cancel a session. It is CANCELLED when the call returns; closing the pane and stopping its
processes finish in the background. Calling it again changes nothing.
Parameters:
session_id(required) - Session ID to cancel
Returns: { session_id, state, changed }. An unknown session is a JSON error {error: {code: "unknown_session", message}}.
list_sessions
List the sessions this server holds.
Parameters:
include_completed(optional) - Include completed, failed, and cancelled sessions (default: false)
Returns: { contract_version: 1, capabilities: [...], sessions: [...] }. Each row has session_id,
model, provider, state, reason, reason_detail, tokens_in, tokens_out, cost_usd (null
for native Claude models), tool_calls, turns_completed, last_activity_at, idle_seconds, activity, started_at,
completed_at and elapsed_seconds. reason_detail is one line (at most 160 characters) saying
why a failed session failed — for api_error, the provider's own error message (no-such-model-zz9 is not a valid model ID) — and null while the session is live, on COMPLETED, and when nothing
readable exists. Team status rows carry the same field. Nothing stops a session for being idle; idle_seconds is for
you to judge.
get_diagnostics
Explain what a session actually did. Call it first whenever a session fails, times out, or
completes with empty or surprising output — it needs no re-run and no debug flag. Returns the
session's final screen, the upstream error bodies, the recent state records, anomalies, the
resolved model chain, accounting, and the paths to the full records (the transcript included).
For a prompt that was not accepted, gate is magmux's current input-gate reading (ready,
reason, detail) and lastSend is magmux's answer to claudish's last gated send (kind,
reason, accept, evidence, retypeCause, attempts).
Parameters:
session_id(required) - Session ID fromcreate_sessionevent_limit(optional) - How many recent state records to include (default 40, max 200)
capture_session
Read a session's current terminal screen at its current size (160×50 unless someone resized it
with resize_session): what you would see if you were looking at its pane. It is a memory read, cheap enough to poll about once a second.
Parameters:
session_id(required) - Session ID fromcreate_sessionsince_seq(optional) - Theseqof your previous capture; when nothing changed the answer is{unchanged: true, seq, final}spans(optional) - Also return each row's colour and attribute runs
Returns: { seq, cols, rows, cursor, lines, final, spans? }. seq grows by one for every visible
change; final: true is the last screen of a closed pane. team(mode:"capture", path, slot) returns
the same shape for a team slot.
resize_session
Set a session's terminal size. The child gets a real resize signal and Claude Code redraws at the
new width; the next capture_session reports the new cols/rows under a new seq. Allowed in
every state, mid-turn included. When several callers resize the same session, the last one wins.
Works with every magmux sessions accept (0.18.0 or newer). Resizing itself needs 0.15.1: 0.15.0
added the resize op, but a pane that grew taller kept its old scroll region, which garbled Claude
Code's input box and stopped its turns from ending. list_sessions and
team list resize in capabilities. If magmux lacks the resize verb, the call answers
resize_unsupported.
Parameters:
session_id(required) - Session ID fromcreate_sessioncols(required) - Columns, an integer; clamped to 40–9999rows(required) - Rows, an integer; clamped to 24–9999, then lowered so thatcols × rowsis at most 4 000 000 (magmux's own limits; 9999 columns leave 400 rows)
Returns: { session_id, cols, rows, changed, seq, pending? }. cols/rows are the size actually
set, after clamping. changed: false means the session already had that size, or has ended (it then
answers its final size). seq is the screen's sequence after the redraw, so a capture with that
since_seq sees the new size. pending: true means the pane is still starting or briefly
disconnected: the size is stored and applied as soon as it can be. Errors are JSON
{error: {code, message}} with unknown_session, invalid_args (missing or non-integer
cols/rows), resize_unsupported, or delivery_unavailable (magmux refused or the pane is
unreachable; the message carries magmux's reason). team(mode:"resize", path, slot, cols, rows) does
the same for a team slot.
Session records on disk
Every create_session session keeps its record under ~/.claudish/sessions/<session_id>/
(CLAUDISH_SESSIONS_DIR overrides the root). Tools that watch sessions from outside the MCP
server read these files; they are a stable contract.
| File | Written | Contents |
|---|---|---|
spawn.json |
once, before the session's pane starts; atomic | schema, kind: "session", sessionId, hostPid (the Claude Code process running this MCP server), mcpPid, startedAt, model, timeoutSeconds, claudeSessionId; launcherPid when claudish runs through the npm launcher; parentClaudeSessionId, the Claude Code conversation live in the calling window when the call ran (read from Claude Code's session record for hostPid, else from CLAUDE_CODE_SESSION_ID; absent when neither has an id) |
waits.jsonl |
one line each time the session starts and stops waiting for send_input |
{"wait":"open","since":…,"turns":…} then {"wait":"closed","since":…,"at":…,"to":…}. Written by interactive sessions, and by any session stopped on a question or permission dialog; append-only, so a wait that opened and closed between two reads still shows. Stops at 1 MB |
meta.json |
once, when the session ends, before its pane is closed | the final record: status, terminalReason, exitCode, turnsCompleted, toolCallCount, costUsd (null for native Claude models), plus state, detail, tokensIn, tokensOut, and parentClaudeSessionId exactly when spawn.json has it |
events.jsonl |
while the session runs | claudish's own records: state changes, tools, anomalies, and one {"type":"assistant","message":{"id":…}} line per model reply. Capped at 4 MB |
output.log, screen.txt |
while it runs / when it ends | the answer prose; the pane's final screen |
A team(mode:"run") gets a record in the same directory, team-<8 hex>/, named by the
monitor_record key of the run result. Its spawn.json has kind: "team", teamPath and
slots in place of the session fields; its meta.json, written atomically once the run
settles (or fails to start), is {"kind":"team","status":…,"startedAt":…,"completedAt":…,"elapsedSeconds":…,"slots":…,"ok":…,"failed":…,"cancelled":…},
plus "reason":"start-failed" when no run started. Session tools such as get_output
answer a team-* id as unknown; use team(mode:"status") for the run itself.
Error Reporting
When a tool call fails (provider errors, model not found, timeouts), the error response includes a hint to use the report_error tool. This applies to:
run_prompt— single model failurescompare_models— per-model failures in comparisonteam— model failures during team runscreate_session— session spawn failures- Sessions that end
FAILED— callget_diagnostics, then report
For plugin authors
If your plugin uses claudish MCP tools, handle error reporting by:
- Check for
isError: truein the tool response — this indicates a failure - Look for the
report_errorhint in the error text — it tells you the error_type and model - Ask user consent before calling
report_error— the tool description requires this - Pass the error context — include
stderr_snippet,model, anderror_type
Example flow in a command:
1. Call run_prompt(model="grok", prompt="...")
2. Response has isError: true
3. Show error to user
4. Ask: "Would you like to report this error to claudish developers?"
5. If yes: call report_error(error_type="provider_failure", model="grok", stderr_snippet="...")
Automatic reporting
Users can enable automatic error reporting via:
claudish config→ Privacy → toggle TelemetryCLAUDISH_TELEMETRY=1environment variable
When enabled, errors are sent automatically without asking. All data is sanitized before sending.
Use Cases
Get a second opinion
Claude, use GPT-5 Codex to review the error handling in this function
Specialized tasks
Use Gemini 3 Pro (it has 1M context) to analyze this entire codebase
Multi-model validation
Have Grok, GPT-5, and Gemini each review this architecture decision, then judge blind
→ team(mode: "run-and-judge", ...)
Budget optimization
Use MiniMax M2 to generate basic boilerplate for these interfaces
Blind judging with team
Run Grok and Kimi on this refactoring task, then have GLM judge the results
→ team(mode: "run-and-judge", path: "./session", models: ["x-ai/grok-3", "moonshot/kimi-k2.5"], judges: ["z-ai/glm-5"])
Configuration
Environment variables
The MCP server reads OPENROUTER_API_KEY from environment.
In Claude Code settings:
{
"mcpServers": {
"claudish": {
"command": "claudish-mcp",
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-...",
"CLAUDISH_MCP_TOOLS": "all"
}
}
}
}
Or export globally:
export OPENROUTER_API_KEY='sk-or-v1-...'
Using npx (no install)
{
"mcpServers": {
"claudish": {
"command": "npx",
"args": ["claudish@latest", "--mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-..."
}
}
}
}
How it works
┌─────────────┐ MCP Protocol ┌─────────────┐ HTTP ┌─────────────┐
│ Claude Code │ ◄──────────────────► │ Claudish │ ◄───────────► │ OpenRouter │
│ │ (stdio) │ MCP Server │ │ API │
│ │ │ │ └─────────────┘
│ polls │ list_sessions, │ Sessions │ headless magmux pane, one per session
│ sessions │ get_output (answers) │ Manager │ ──────────► claudish -i → Claude Code
│ │ ◄──────────────────► │ │ (interactive)
└─────────────┘ └─────────────┘
run_prompt flow:
- Claude Code sends tool call via MCP (stdio)
- Claudish MCP server receives it
- A non-Claude model: the server calls it through the proxy engine. A bare Claude name: the server
runs one
claudish -pon your Claude Code login - Response returned to Claude Code
Session flow:
- Claude Code calls
create_session - Claudish starts a headless magmux pane running an interactive Claude Code on your model
- The session manager follows Claude Code's own transcript and screen and writes the session's state and records
- Claude Code polls
list_sessionsfor the state - On completion, Claude Code calls
get_output
The pane is closed when the session ends, and nothing it started outlives the MCP server: if the server exits — even if it is killed — a small watcher process per pane stops the pane and removes its files.
CLI vs MCP: when to use which
| Use Case | Mode | Why |
|---|---|---|
| Full alternative session | CLI | Replace Claude entirely |
| Get second opinion | MCP | Quick tool call mid-conversation |
| Batch automation | CLI | Scripts and pipelines |
| Model comparison | MCP | team runs several models on one task |
| Interactive coding | CLI | Full Claude Code experience |
| Specialized subtask | MCP | Delegate to expert model |
| Blind judging | MCP | team tool with anonymized outputs |
| Long async task | MCP | create_session, polled with list_sessions |
Debugging
Check if MCP server starts:
OPENROUTER_API_KEY=sk-or-v1-... claudish --mcp
# Should output: [claudish] MCP server started (tools: all, 15 tools)
Test the tools:
Use Claude Code and ask it to list available MCP tools. You should see all 15: run_prompt, list_models, search_models, compare_models, preflight, team, report_error, create_session, send_input, get_output, cancel_session, list_sessions, get_diagnostics, capture_session, and resize_session.
Check which tool group is active:
CLAUDISH_MCP_TOOLS=session OPENROUTER_API_KEY=sk-or-v1-... claudish --mcp
# [claudish] MCP server started (tools: session, 8 tools)
Write the debug log (logs/ in the server's working directory; standard output stays
JSON-RPC only):
claudish --mcp --debug-claudish # or -d, or CLAUDISH_DEBUG=1
Check magmux (needed by team and sessions):
magmux --version # 0.18.0 or newer
Limitations
Streaming: MCP tools don't stream. You get the full response when complete.
Context: The MCP tool doesn't share Claude Code's context. Pass relevant info in the prompt.
Rate limits: OpenRouter has rate limits. Heavy parallel usage might hit them.
Platforms: team and sessions need magmux 0.18.0+ and run on macOS and Linux only; Windows is not supported for them.
Next
- CLI Interactive Mode - Full session replacement
- Model Selection - Pick the right model