Skip to main content
The Claude Code adapter connects Orkestral to the claude command line tool from Anthropic. It is one of the bundled provider adapters, and Orkestral marks it as recommended. In Orkestral, premium provider adapters PLAN and the local Forge EXECUTES code changes. When you assign the Claude Code adapter to an agent, that agent uses your local claude CLI to reason and plan. Orkestral runs the CLI as a child process on your machine, so the work uses your own Claude subscription or API credits, not an Orkestral key.

​
What it is

The adapter wraps the claude binary. It does three things:
  • Lists the Claude models you can pick for an agent.
  • Runs an environment test to confirm the CLI is installed, responds, and is logged in.
  • Invokes the CLI in non interactive mode so an agent can plan without manual prompts.
Internally the adapter type is claude_local and its display name is Claude Code.

​
Requirements

claude CLI installed

The claude binary must be on your PATH. Install it with npm i -g @anthropic-ai/claude-code or follow the official Anthropic guide.

Authenticated

You must be logged in. Run claude login in a terminal before using the adapter, or sign in with your Anthropic account or API key.
Orkestral never stores Anthropic credentials. Authentication lives entirely in the claude CLI on your machine. Orkestral only spawns the binary and reads its output.

​
How Orkestral runs the CLI

Orkestral calls claude directly as a child process (no shell), passing the prompt through standard input. For the environment test it runs: 
claude --print - --dangerously-skip-permissions
  • --print makes the CLI return a single non interactive response instead of opening a session.
  • - tells the CLI to read the prompt from stdin.
  • --dangerously-skip-permissions avoids the interactive permission prompts that would otherwise block an automated run.
The probe sends a minimal prompt (Respond with hello.) and inspects the output to decide whether the CLI is healthy, needs login, or returned something unexpected.

​
Set it up

1

Install the CLI

Install the Claude Code CLI globally and confirm it is reachable:
npm i -g @anthropic-ai/claude-code
claude --version
2

Log in

Authenticate the CLI so it can answer requests:
claude login
3

Add the adapter in Orkestral

Open the adapters grid in onboarding or settings and select Claude Code. Orkestral runs its environment test automatically.
4

Pick a model and options

Choose a model from the list and adjust the configuration fields described below.
5

Assign it to an agent

When you hire or edit an agent, set its provider to Claude Code so it plans with this adapter.

​
Models

The adapter exposes explicit model versions (newest first) plus tier aliases. Aliases resolve to the newest model in their tier on the CLI side.
Model idLabelNotes
defaultDefault (configured in the CLI)Uses whatever model the CLI is set to
claude-opus-4-8Claude Opus 4.8Explicit version
claude-opus-4-7Claude Opus 4.7Explicit version
claude-sonnet-4-6Claude Sonnet 4.6Explicit version
claude-haiku-4-5Claude Haiku 4.5Explicit version
opusOpus (alias)Newest model in the Opus tier
sonnetSonnet (alias)Newest model in the Sonnet tier
haikuHaiku (alias)Newest model in the Haiku tier
Pick default if you want Orkestral to follow whatever model your CLI is already configured to use. Pick a tier alias (opus, sonnet, haiku) if you want the latest model in that tier without pinning a version.

​
Configuration options

The adapter exposes these fields in its config form.
​
effort
select
default:"medium"
Reasoning effort. One of low, medium, or high. Passed to the CLI via the --effort flag.
​
chrome
toggle
default:"false"
Enables browser tools (Chrome) for the agent.
​
instructionsFilePath
file
Path to a Markdown instructions file (for example /path/to/INSTRUCTIONS.md). Its contents are injected into the system prompt at runtime.
​
command
text
default:"claude"
Override for the command used to invoke the CLI. Accepts a path or a command name. Defaults to claude. Use this when the binary is not named claude or is not on your default PATH.

​
Environment test

When you add or test the adapter, Orkestral runs an ordered set of checks. The overall result is the worst of the individual checks: any failure makes the whole test fail, any warning makes it a warning, otherwise it passes.
Orkestral looks up the claude binary with which (or where on Windows). If it is not found, the test fails and stops here with an install hint.
Runs claude --version with a 5 second timeout. If the CLI does not respond, the test fails and reports the error from the CLI.
Sends the Respond with hello. probe with a 45 second timeout. A reply containing hello passes. Login errors, timeouts, or unexpected output produce a warning with a short detail message.

​
Capabilities and limits

  • Runs fully on your machine. Orkestral spawns the binary directly, with no shell, to avoid injection.
  • Uses your own Claude authentication and quota. Orkestral does not proxy or meter the calls.
  • The probe closes stdin after sending input, so the CLI does not hang waiting for more data.
  • This adapter is a planning provider. Code execution in Orkestral runs through the local Forge, not this adapter.

​
Troubleshooting

The binary is not installed or not on your PATH. Install it with npm i -g @anthropic-ai/claude-code, then reopen Orkestral so it picks up the updated PATH. If the binary has a different name or location, set the Command (override) field to its full path.
The probe detected an authentication problem (messages like please log in, claude login, not authenticated, or unauthorized). Run claude login in a terminal, then test the adapter again.
The probe did not finish within 45 seconds. Try testing again, or run claude in a terminal to confirm the CLI works interactively. A slow first response or network issue can trigger this warning.
The CLI answered but did not include hello. This is usually harmless. Check the detail message shown in the test result, and confirm the CLI works on its own.

Adapters overview

Learn how provider adapters and the local Forge split planning from execution.

Hiring agents

Assign the Claude Code adapter to an agent on your team.