@agentclientprotocol/claude-agent-acp. The adapter brings its own Claude Code, so you don’t have to install the claude CLI.
What you need
Node.js withnpm, from nodejs.org. Arakun uses it once, to install the adapter.
The first Claude Code session asks before it installs the adapter. It shows the package, the folder and the npm command. Click Install, or run the command yourself and click Retry. The adapter goes in ~/.local/share/arakun/agents, or %LOCALAPPDATA%\arakun\agents on Windows. After that, Arakun updates it to the version it was built with, without asking.
The adapter runs the Claude Code binary that comes with it, so its version can differ from the claude in your terminal. It uses the claude on your PATH only when its own is missing. CLAUDE_CODE_EXECUTABLE picks another binary.
Sign in
Claude Code runs on one of these:- Your claude.ai plan. Open Settings › Claude Code and click Sign in, or press Ctrl+K and pick Sign in to Claude Code. A terminal runs
claude /login; approve the sign-in in the browser. If you already signed in toclaudein a terminal, Arakun finds it in~/.claudeand you’re done. You don’t need a project open to sign in. - An API key or another endpoint. Set
ANTHROPIC_API_KEY,ANTHROPIC_AUTH_TOKENorANTHROPIC_BASE_URLin~/.claude/settings.jsonor the environment. That covers a gateway or CLIProxyAPI too. Amazon Bedrock, Google Vertex AI and Microsoft Foundry work through Claude Code’s own settings.
Your settings carry over
The adapter loads your user, project and local settings. Your skills, hooks, plugins, MCP servers,CLAUDE.md and permission rules work as they do in the terminal. Skills you install from the Marketplace go in ~/.claude/skills.
A new session starts in the permission mode set in permissions.defaultMode. Without one, it starts in Auto when Claude Code offers it.
Pick a model
The menu next to the composer lists the models Claude Code offers, a row of reasoning levels and a Fast mode switch. Default (recommended) shows which model it stands for. Arakun also adds Fable 5.2, which Claude Code can run but doesn’t list yet. The environment remembers your pick for its next session. The chip next to it sets the permission mode, Plan mode among them. In Plan mode you approve the plan before Claude Code starts.Usage
The Usage tab reads token use and cost from Claude Code’s own logs, so sessions you run in a terminal count too. Signed in with a plan, it shows the 5-hour and weekly limits with their reset times. The session footer shows a limit as it fills up, and Arakun sends a desktop notification at 80% and when it is used up. When Claude Code runs on CLIProxyAPI, add the proxy’s management key in the Usage tab. It then shows the 5-hour and weekly limits of every Claude and Codex account behind the proxy, and which ones the proxy holds back. The key goes only to that proxy, over https or on this machine.Spread sessions over several plans
With several Claude subscriptions, give each Claude Code session a seat of its own, so parallel sessions don’t drain one plan.1
Make a token per subscription
Run
claude setup-token while signed in to that subscription. It prints a long-lived token.2
Save it as a seat
~/.local/share/arakun/seats/work, readable only by you.arakun seat lslists the seats and their usage.arakun seat rm workforgets one.- Starting a session on a seat checks its token first, so a dead token shows up at the start. A seat whose token is refused is skipped, and the session says so.
- Seats don’t work while Claude Code runs on an API key, a gateway or a cloud provider, or while
~/.claude/settings.jsonsetsCLAUDE_CODE_OAUTH_TOKENin itsenvblock. Sandboxed sessions don’t use seats either.
Good to know
- With Sandbox agents on in Settings › Project, Claude Code runs in a sandbox. On Linux it then keeps its settings in
~/.claude/.claude.json, a copy of~/.claude.jsonat first. arakun agent new --model claude/<model> <prompt>starts a Claude Code session from a terminal. It shows in the app and asks for permissions there.- Claude Code (with
haiku) can name new branches after the task. See Start a session.
What does not work yet
- Commands that only make sense in the terminal app are left out:
/clear,/cost,/keybindings-help,/login,/logout,/output-style:new,/release-notes,/todosand others. - The status line and keybindings from your settings don’t apply in Arakun.
- With an API key or another endpoint there are no plan limits to show.
- Headless agents can’t run Claude Code yet.
Common errors
npm was not found
npm was not found
Install Node.js, which includes npm, then click Retry.
Claude Code is not signed in
Claude Code is not signed in
Click Sign in in a terminal under the error, or run
claude in a terminal and sign in with /login. Then click Retry.Claude Code's own binary is missing
Claude Code's own binary is missing
An antivirus may have removed it. Allow the folder
~/.local/share/arakun/agents (on Windows %LOCALAPPDATA%\arakun\agents) and restart Arakun. Or set CLAUDE_CODE_EXECUTABLE to a claude binary. The error names the log with the details.Claude Code's 5-hour limit is used up
Claude Code's 5-hour limit is used up
The composer says when it resets, and offers to switch a new session to Droid. Or sign in with a plan that has room, add a seat, or use an API key.
Use another adapter
ARAKUN_CLAUDE_ACP runs another adapter command instead of the one Arakun installs, and skips the install.