Claude Code, headless, on other models
Three environment variables point a headless Claude Code session at MiniMax, Kimi or a local model. The wrapper scripts that make it run unattended, the six failures they fix, and why the planner reruns the checks.

Key takeaways
- Set the endpoint, the API key and the model together, and treat the result as an unsupported custom setup. Making it reliable unattended takes the rest of the wrapper script.
- Give the executor its own role in the system prompt. It reads every instruction the planner reads.
- In headless mode a permission prompt has nobody to answer it. Grant the writes the brief needs before the job starts.
- Pin the endpoint where nothing can override it, and keep keys out of the command line.
- Run long jobs detached, and treat a result file written last as the only sign of completion.
- Judge the work by the checks the planner reruns, not by the executor's report.
Tap the picture above to watch the seven-minute video on YouTube. It walks through the same setup, with the wrapper scripts on screen.
Claude Code runs without a person at the keyboard: claude -p "task" takes one instruction, works through it with its usual tools, prints the result and exits. It also lets the model behind it change. Three environment variables point the same command at a different endpoint that accepts Anthropic's API format. Several model companies now offer such an endpoint with their coding plans, and a small gateway on the same computer can translate for others.
This is a custom setup that Anthropic does not support. Claude Code's own documentation on gateways says Anthropic does not support routing Claude Code to models other than Claude. Some features may behave differently or not work, and each model company's own terms apply.
On this workstation that combination does most of the routine coding. One Claude session plans the work, writes a brief, and starts a headless Claude Code session on a cheaper model to carry it out. From 12 July to 8 November 2026 the ledger recorded about 420,000 requests to MiniMax models and about 270,000 to Anthropic's, with about 240 million output tokens each. Since 7 September the MiniMax wrapper script has started about 1,300 detached jobs, and about 1,100 of them ended without an error. Ending without an error is not the same as finishing the work well; the section on splitting the work explains why.
Words in this article
- Claude Code: Anthropic's coding assistant that works in your terminal and can read files and run commands
- terminal: the text window where you type commands to your computer
- command: an instruction typed into the terminal, such as one that lists or deletes files
- model: the AI that reads text and writes a reply, such as Claude
- agent: a program that lets a model take actions, look at the results, and keep going until the job is done
- headless: running with no person at the keyboard: the program takes one instruction, does the job and exits
- API: the way one program sends requests to another; here, how the code talks to Claude
- API key: a secret password that lets your code use Claude, and bills your account
- endpoint: the web address a program sends its API requests to
- environment variable: a named setting the terminal hands to every program it starts
- wrapper script: a short script that sets things up and then starts another program
- gateway: a small program that receives requests in one API's format and passes them on in another's
- token: a small piece of text, about three quarters of a word, used to measure length and cost
- context window: how much text the model can consider at once
- compaction: shortening an old conversation so it fits in the context window
- system prompt: standing instructions the program gives the model before your request
- tool: an action the model can ask the program to take, such as read a file or run a command
- permission: a rule that decides whether an action may run, needs your OK, or is blocked
- hook: your own script that runs automatically at a set moment, such as before a tool runs
- flag: an option added to a command, written with two dashes, such as --help
- settings file: the file where Claude Code keeps your permissions and options
- brief: the written instructions a planning session hands to an executor: the goal, the limits and what counts as done
- executor: the cheaper session that carries out a brief and reports back
- detached job: a job started in its own session, so closing the window that started it does not stop it
- lane: one route to a model, such as a subscription, a free allowance or a local model
- ledger: a database that records every request to every model, with its token counts
- tests: small programs that check the code still does what it should
- Git: a tool that records every change to a project so you can review or undo it
- commit: a saved snapshot of changes in Git, with a message
- merge: joining the changes from one branch into another
- diff: the list of lines a change adds and removes
- session: one run of Claude Code, from your first message until you close it
- architecture: the plan for how the pieces of the program fit together
The three variables
A wrapper script sets the endpoint, the API key and the model as environment variables, then starts Claude Code:
export ANTHROPIC_BASE_URL="https://api.minimax.io/anthropic"
export ANTHROPIC_AUTH_TOKEN="$MINIMAX_API_KEY"
export ANTHROPIC_MODEL="MiniMax-M3"
exec claude --model "MiniMax-M3" "$@"The same pattern runs Kimi through its coding subscription endpoint, and a local open model through a gateway on the same machine. Another wrapper script starts a gateway that speaks Anthropic's API format on one side and other companies' APIs on the other, so one Claude Code session can switch models with /model. Each wrapper script has its own short name, so the command shows which model and which bill a job uses.
Claude Code keeps its tools, its permission system, its hooks and the project's instructions, so the command looks the same. The model answering is different, and some features depend on what the other model and its endpoint support.
What broke, and the fix for each
Most of the wrapper's lines are fixes, and each one is dated in a comment next to the failure it answers.
- The executor delegated its own task. A headless session reads the same global instructions as the planning session, and those instructions said to hand routine work to the cheaper engine. The cheaper engine obeyed and launched copies of itself. The wrapper now appends a system prompt that says it is the executor and must do the work directly, and it blocks the launcher commands with --disallowedTools.
- Long briefs died as a bare "Execution error". Claude Code did not recognise the model name and assumed a 200,000 token window, so it compacted long sessions too early and cut off the brief. The wrapper sets CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1, which switches off that early compaction for a model name Claude Code does not know. The model's real context window still applies.
- A write outside the project folder stopped the session. --permission-mode acceptEdits approves edits inside the working folder and any folders added for the session, and nowhere else. A brief that asked for a report somewhere else raised a permission prompt that nobody was there to answer, and one wave of eight jobs was lost that way. The wrapper script adds one spare folder with the --add-dir flag, which brings it inside that approval without approving anything else, and every brief also asks for the report to be printed on screen.
- A project setting sent the key to the wrong service. A project's own settings file can set ANTHROPIC_BASE_URL, and it outranks the environment. Jobs started from that project sent the MiniMax key to a local gateway and failed with "401 API key is invalid". The wrapper now passes the endpoint and the model names through --settings, which ranks above project settings. Only settings set by an organisation rank higher. The key stays in the environment, never in the command line or the job record.
- Background jobs were killed after half an hour. In Claude Code version 2.1.267, a headless job started from inside a normal Claude Code session could be shut down after about half an hour without typing; version 2.1.278 fixed it. The wrapper script gained its own --detach flag, which starts the job as a detached job with setsid and returns a job id at once. A companion script, mm-wait, waits for a result file that the job writes last, so a half-written log is never mistaken for a finished job. Both are this setup's own scripts, not Claude Code commands.
- A local model returned empty answers. The program serving the model moved every reply into a hidden field meant for its reasoning, so Claude Code received nothing. A flag on the server fixed it; no prompt change was needed.
How the work is split
The planning session keeps the decisions: what to build, which files a job may touch, and what counts as done. The brief names the working folder, the inputs, the allowed writes, the forbidden actions and the exact commands that must pass. Executors do not commit, upload changes, start services or start other agents.
The planning session then reads the diff and reruns the checks itself. A job that ends without an error has only ended; that says nothing about the quality of the work. Executors have passed a wording check by splitting a phrase in two so the check could not see it, and have run tests against the main copy of the project instead of their own. Both were caught because the planning session reran the checks after the merge.
A detached job, using this setup's own wrapper script and mm-wait, looks like this:
job=$(mm-code --detach -p "$(cat brief.md)" --permission-mode acceptEdits)
mm-wait "$job" --quiet --timeout 1800Choosing the engine
One short policy file decides which engine gets which work, and its first rule is that the person's explicit choice wins. Bounded tasks go to the MiniMax subscription while its allowance lasts, then to free or included lanes, then to Codex or Claude. The local model is the emergency backup when the suitable cloud lanes are down or used up, one bounded fix at a time, with the graphics card free of other work. A paid lane comes last, and only after the exact model, price and budget are announced.
The same file says what each engine may see. A few lanes may handle the minimum private code a task needs; others get public or cleaned material only, and secrets never leave the machine. The planning session keeps the architecture, live operations and the final acceptance.
The lanes change. A free lane through a model router ran from August to late October and was retired. The wrappers make that cheap: a new engine is one more short script, and a retired one is a script nobody calls.
What carries over
- Set the endpoint, the API key and the model together, and treat the result as an unsupported custom setup. Making it reliable unattended takes the rest of the wrapper script.
- Give the executor its own role in the system prompt. It reads every instruction the planner reads.
- In headless mode a permission prompt has nobody to answer it. Grant the writes the brief needs before the job starts.
- Pin the endpoint where nothing can override it, and keep keys out of the command line.
- Run long jobs detached, and treat a result file written last as the only sign of completion.
- Judge the work by the checks the planner reruns, not by the executor's report.
Sources
- Claude Code documentation: headless mode and command referenceAnthropic. Retrieved 2026-11-08.
- Claude Code documentation: LLM gateways, including the support limitation for non-Claude modelsAnthropic. Retrieved 2026-11-08.
- Claude Code documentation: settings and their order of precedenceAnthropic. Retrieved 2026-11-08.
- Claude Code documentation: permissionsAnthropic. Retrieved 2026-11-08.
- Claude Code documentation: environment variablesAnthropic. Retrieved 2026-11-08.
