---
title: Switch AI coding tool — checked first, switched only if it works
nav: Switch AI tool
summary: Send the switch command from the phone menu; your main Agent explains, scans this computer for Claude Code, Codex and OpenCode, tries each sign-in headless, switches only to one that works, and the new tool introduces itself — or Agent J switches back by itself.
order: 29
---
# Switch AI coding tool — checked first, switched only if it works

An AI coding tool is the program on this computer that actually thinks and does the work: Claude Code, Codex or OpenCode. Agent J is the line from your phone to it. Switching changes who answers you; the work folder, the phone, approvals and the safety rules stay the same.

## How to start

- In ≡ "All commands" left of the message box, the "Run now" group (under `/customize`) has the switch command (`/switch-harness`); one tap sends it to your main Agent. To name the target yourself, type the command in the box, add "switch to Codex" after it and send it.
- Or just say "switch to OpenCode" or "back to Claude Code".

Nothing switches when you tap it. The command goes to your current main Agent, which follows a fixed procedure.

## What your main Agent does

1. **Explains.** If you sent the command with no words, it first says in two or three sentences which kind of tool it means and how to switch.
2. **Scans** which AI coding tools this computer has, and their versions.
3. **Tries each sign-in.** For every installed tool it makes one tiny headless call with your own login and the model the tool would run with (no tool permissions, at most 60 seconds each) to see whether it answers now. This runs in a separate small job on the computer, in the environment of Agent J's background service — exactly what the tool gets after a switch. Read-only: no config is changed, no key is read out or shown.
4. **Tells you**, for example, "you can switch to: Codex, OpenCode" — or "only the current one works on this computer; to switch, install another one first". For an installed one that does not work it says why: not signed in, an expired token, or no network / proxy.
5. **Helps install, guides the sign-in.** With your yes it installs a missing one following [Set up AI command-line tools](/docs/setup-agents/). Signing in is yours: it tells you step by step what to run in your own terminal, what you will see and what to click — `claude auth login` for Claude Code, `codex login` for Codex, `opencode auth login` for OpenCode. A model API key never goes through the chat; it uses the masked key card on your phone. Then it tries again.
6. **Switches** only to a target that just passed, and only when you clearly ask.

## What happens during the switch

Your main Agent first says: Agent J restarts, the phone disconnects for a few seconds and reconnects by itself. Then it runs `agentj agent switch <target>`:

- The command tries the target's sign-in once more — the last gate. If it fails, nothing changes and your Agent tells you why.
- If it passes, a separate small job on the computer takes over: it waits for the current reply to finish, switches, restarts Agent J and checks that the new tool is up and answers.
- For Codex the gate also opens its long-running session once, the way it will run after the switch: the same work folder, your own Codex settings with their MCP servers and plugins (nothing is kept in your Codex history, no message is sent). If that session cannot open, nothing changes and you get the reason. If it opens slowly, the switch waits for it accordingly.
- After the restart, a tool that is still visibly starting is waited for, up to 8 minutes. If it still says nothing, `agentj agent switch --result` and the switch-back message say where it stopped — still starting, waiting at a prompt in a terminal, waiting for an approval card, failed to start, or started but silent — plus the error type if it printed one, and what to do next.
- When all is well, the new tool greets you first: which one it is and which model it runs.
- If any step fails, Agent J switches back to the previous tool by itself, restores the earlier settings exactly, and the previous one tells you it did not work and why.

So even away from the computer, without a terminal, you cannot be cut off by switching to a tool that does not work.

## A handoff before every switch

Each tool keeps its own conversation, so the new one cannot see what you just talked about. Before switching, Agent J has the tool you use **now** write a handoff file in the same format as the [compaction handoff](/docs/compaction/); after the switch the new tool **reads it first, then carries on**.

- The handoff is written after the checks pass and right before the switch. Only the essentials: your key points in your own words, progress, decisions already made, key paths and commands, pitfalls, the next step and questions waiting for you; at most 150 lines, never a key, token or password.
- Fixed places: `<work folder>/.agentj/handover/switch.md` for an independent session, `~/.local/state/agentj/handoff/switch.md` for a shared one. Switching back works the same way: the one leaving writes, the one taking over reads, and the same file is merged and updated.
- The new tool reads the handoff before it greets you and says what it picked up; then Agent J has it carry on with the handoff's next step. If nothing was in progress, it waits for you.
- Agent J waits at most 3 minutes. If no handoff was written the switch still happens: the phone says "No handoff this time", and the new tool tells you it does not know what was said before, so the key points may need repeating.

## Switching there means being able to come back

- Before switching, the tool you use **now** is tried the same way as the target. If it fails in the background service (for example because its login lives only in your terminal's environment), there would be no way back after the switch, so by default nothing is switched and you are told how to fix it first. To switch anyway, add `--force`.
- Already switched and the check will not let you go back? Run `agentj agent switch --undo` on the computer (or ask the main Agent to): with no pre-check it restores the tool from before the last switch exactly as it was; if that one does not come up, Agent J returns to the current one by itself.
- When the background service finds no Claude Code login, it says what to do: run `claude` in a terminal and `/login` once (on a Mac the login goes to the Keychain, which the service can use too), or in a terminal where claude works run `agentj service import-key CLAUDE_CODE_OAUTH_TOKEN`, then `agentj service restart`.
- When a tool has updated itself (say Codex from 0.156 to 0.162), an older path the background service had saved is dropped and the one your terminal finds is used; the scan says so.

## Switching never needs the admin password

Whichever tool is working now, including OpenCode, Kimi Code and Qwen Code running inside the isolation, switching, scanning and `--undo` go through Agent J's own background service: no admin password, and no need to go back to the computer and open a terminal.

- If your Agent says "the service is not loaded" and asks for the admin password, or asks you to run `agentj service start` in a terminal, you don't need to. Inside the isolation it can't see the system's service manager, so it may think the service has stopped.
- To check whether the service is running, run `agentj service status`. It asks the running service itself and says it is running whenever the service answers.
- Agent J never asks for the admin password to manage its own background service either; such a request is refused.

## OpenCode with no key

- OpenCode comes with a few free models of its own (`opencode/…`, mostly ending in `-free`): no account, no key, no payment. With one of them OpenCode counts as usable without a key; switch with `agentj agent switch opencode --model opencode/<free-model>` — `opencode models opencode` lists the current ones (they change almost daily).
- A free model is checked on the same path as a normal chat (OpenCode refuses requests that do not look like its own client); in the first minute or two after installing it is sometimes refused, and the check waits and retries by itself — at most a minute or so longer.
- Some free models' providers log the conversation or train on it: when you pick one, the switch result and the phone's "Models & API keys" page add one sentence saying so. Keep personal or confidential things out of it, and use a model of your own for everyday use.
- After writing the setting, the switch job reads it back; if it does not match, nothing is switched.
## What the phone shows while you wait

A scan can take about three minutes, and a switch restarts Agent J once. The reply card is never blank meanwhile: its text starts with a small dancing robot followed by Agent J's own progress line: which tool it is probing (and which of how many), which one it is switching to, or that it is back on the previous one, which will tell you why in a moment. As long as the robot dances, your message is not lost and nothing has stopped.

## Good to know

- Each tool keeps its own conversation. After a switch you are in that one's conversation; switching back continues the earlier one.
- Isolation, shared or independent session, the work folder and the approval rules are unchanged by a switch.
- In shared mode the new tool needs a session to attach to: Claude Code must be open on the computer; Codex and OpenCode start a new one in the same folder when none is open.
- A Codex conversation that is read-only cannot run the switch command; your Agent tells you Codex's refusal — that conversation needs Full access.
- To see the last switch's outcome, run `agentj agent switch --result` on the computer, or ask your main Agent.

```bash
agentj agent switch --scan
```

```bash
agentj agent switch codex --dry-run
```

The first shows which ones you can switch to now (each tried in the background service's environment); the second only checks whether Codex would pass, without switching.

## Kimi Code {#kimi}

Kimi Code CLI (`kimi`, by Moonshot AI, MIT licence, 2.2.0 or newer) is the fourth AI coding tool Agent J can switch to — a common choice where Claude Code and Codex are not offered (mainland China, Hong Kong, Macau). Agent J talks to it over the Agent Client Protocol (`kimi acp`): one long-running conversation per Agent, replies in whole pieces, every approval on your phone.

- Switch with `agentj agent switch kimi`; a membership bought on kimi.ai adds `--region global`. The same check-first gate, handoff and automatic switch-back apply. Kimi Code runs in an independent session only (no shared terminal session yet).
- Sign in from the phone: Settings → Emergency repair → ③ AI account signed out → AI login rescue → Kimi Code → Sign in again (device code). The computer runs the official `kimi login`, the phone shows a link and a one-time code, and you confirm on any device signed in to Kimi. At the computer it is `kimi login --region mainland-cn` (kimi.com, the default) or `kimi login --region global` (kimi.ai). A key from a kimi.com membership works on both api.kimi.com and api.kimi.ai.
- A Kimi Code console API key works too: the Agent sends a phone key card for `KIMI_API_KEY` — never paste it into the chat. Agent J hands it to Kimi in memory, and only when Kimi has no login of its own.
- Approvals stay with you. Kimi's own hooks let a call through when they fail or time out, so Agent J does not rely on them: every Kimi conversation is kept in Kimi's manual mode, each permission request becomes a phone card, and a yes covers this one call only, never later ones. If Kimi switches itself to Auto or YOLO, Agent J switches it straight back. Kimi has no sandbox of its own: it runs inside Agent J's isolation, with its dangerous-command guard forced on. Allow rules you wrote yourself in `~/.kimi-code/config.toml` stay yours; `agentj doctor` says how many there are.
- Skills: Kimi reads `~/.agents/skills`, where Agent J already links its bundled skills, so they work unchanged. A plaza package installs its Codex version for Kimi.
- Prefer OpenCode with a Kimi model? That route stays; `agentj agent route` offers both.

## Qwen Code {#qwen}

Qwen Code (`qwen`, by Alibaba, Apache-2.0, 0.25 or newer) is the fifth AI coding tool Agent J can switch to, a natural pair with an Alibaba Cloud Bailian Token Plan in mainland China ([setup](/docs/setup-agents/#bailian)). Agent J talks to it over the same Agent Client Protocol as Kimi Code (`qwen --acp`).

- Switch with `agentj agent switch qwen`. The same check-first gate, handoff and automatic switch-back apply. Independent sessions only.
- Its free sign-in ended on 2026-04-15, so a key is its login: the Agent sends a phone key card for `BAILIAN_TOKEN_PLAN_API_KEY`. Agent J hands the key to Qwen Code in memory only; your own `~/.qwen/settings.json`, if you set one up, wins.
- Approvals stay with you. Qwen Code starts in a mode where a classifier approves some actions by itself; Agent J switches every conversation back to asking, and each request becomes a phone card for that one action.
- /model on the phone lists the plan's models; those marked as reading images can look at screenshots. Changing the model restarts Qwen Code and continues the same conversation.
- Your own scheduled tasks may use the Token Plan key too (the provider may rate-limit long, continuous background work; you can switch those to a pay-as-you-go key); a support bot serves other people, so Agent J never gives it that key.

## DeepSeek dsh {#dsh}

DeepSeek's dsh (`DeepSeek Harness`, MIT, 0.2.0-rc.2 or newer, a developer preview) is the sixth AI coding tool Agent J can switch to. It is the engine inside Olares' own agent Lares, and it works with any OpenAI-compatible model server ([setup](/docs/setup-agents/#dsh)). Agent J talks to it over the same Agent Client Protocol as Kimi Code (`dsh --profile acp`).

- Switch with `agentj agent switch dsh`. The same check-first gate, handoff and automatic switch-back apply. Independent sessions only.
- No model yet? The check says so: `agentj agent dsh --base-url https://<server>/v1 --model <model id>` sets one up. A key goes only through the phone key card (`DSH_ROUTER_API_KEY`, or `DEEPSEEK_API_KEY` for DeepSeek's own API). Your own dsh setup, if you have one, is used as it is.
- Approvals stay with you. Agent J starts dsh read-only, asking every time: each file change or command that is not read-only becomes a phone card for that one action, never "always".
- /model on the phone lists the route's model and DeepSeek's models; /context works. dsh compacts its own conversation when it gets near the limit (there is no /compact for it). A model server of your own has no plan quota.
- It reads text only for now. Scheduled tasks may use it, but never get a key from the key card.