Skip to content

Claude CLI ​

See the generated compatibility matrix for capability details and version-scoped evidence.

claude-cli runs ctrlyoke workflows through Claude Code while keeping the same workflow file format used elsewhere.

The dashboard after a three-step demo workflow ran on Claude Code, with 5% quota used shown next to Claude Code in the harness picker

Good fit ​

  • Teams that already use Claude Code directly
  • Workflows that want the ctrlyoke queue, history, and script gating on top of Claude Code

Prerequisites ​

  • Command: claude, on your PATH.
  • Install: see Install.
  • Sign in: run claude once in a terminal and complete the sign-in.
  • Version: at least the minimum listed under Supported versions. Update with claude update.

If the CLI is missing, the harness picker shows a red dot next to Claude Code, and its tooltip gives the install command. If it is installed but older than the minimum, it still runs: the picker shows an amber dot and the update command, a workflow that uses it warns when it starts, and a failed step repeats that command. After installing or updating, click Retry harness detection in the harness picker. If no harness CLI is available at all, the dashboard shows a No CLI coding agent is available panel with the install command for every harness.

Install ​

Install Claude Code with Anthropic's native installer, which keeps itself up to date:

macOS and Linux:

bash
curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

powershell
irm https://claude.ai/install.ps1 | iex

Homebrew (brew install --cask claude-code), WinGet (winget install Anthropic.ClaudeCode), and npm (npm install -g @anthropic-ai/claude-code) also work, but do not update themselves.

See Claude Code's setup guide for other install methods.

Example ​

yaml
harness: claude-cli
model: sonnet

steps:
  - name: analyze
    prompt: Inspect @src/server/ for security gaps.
  - name: fix
    resumeSession: true
    prompt: Implement the fixes.

Model selection ​

When ctrlyoke starts, it asks the installed Claude Code which models your account can use, so the Model picker shows the same models and names as Claude's own /model picker. That list has Claude's aliases (opus, fable, sonnet and haiku), each of which always runs the newest model of its family. The older versions your account still offers, such as claude-opus-4-6, start out in the picker's hidden section, as they sit behind More models in Claude's picker: click Show hidden to see them, and unhide one to keep it in the list. Pick an alias to move to new models automatically, or a version to stay on it. ctrlyoke asks without starting a session, so the lookup uses no tokens.

If Claude Code isn't installed or doesn't answer, the picker falls back to the four aliases.

Set model on the workflow or on a step. Without one, ctrlyoke uses defaults.models["claude-cli"], which is none out of the box: no --model flag is passed, so Claude Code uses its own default model for your plan. A full model ID is passed to Claude Code as written, so the version it pins is kept. That includes Anthropic IDs such as claude-opus-4-6, Amazon Bedrock IDs such as us.anthropic.claude-sonnet-4-5-20250929-v1:0 and Bedrock inference-profile ARNs, and Google Vertex AI IDs such as claude-sonnet-4-5@20250929. A Copilot-style ID such as claude-sonnet-4.6 is mapped to the alias for its family (sonnet), and so is the old sonnet[1m] or opus[1m]: Sonnet and Opus now always run with a 1M context. Any other value is replaced by your default, with a warning in the log; if the default is none, no --model flag is passed. The ctrlyoke CLI doesn't look the model list up, so it passes any other value to Claude Code as you wrote it. Keep model overrides harness-specific.

model: none passes no --model flag, so Claude Code uses its own default model. See How step properties inherit.

A newer model can need a newer Claude Code than ctrlyoke's minimum (Fable needs 2.1.170 or later), and an older release resolves sonnet, opus and haiku to older models. If a model you expect is missing, or a step fails because the selected model may not exist or you may not have access to it, run claude update and restart ctrlyoke.

Permissions ​

The sandbox property is separate from approval modes. true adds one merged --settings payload that enables Claude's Bash sandbox, refuses to run if it is unavailable and keeps approvals governed by toolPermissions. With sandboxMode: workspace-write Bash can write ctrlyoke's approved roots (allowWrite); with read-only it can't write them (denyWrite). false passes sandbox.enabled: false, which turns off a sandbox enabled in your own Claude settings too, unless a managed settings file enforces it. null adds no sandbox settings, so Claude's own settings decide. ctrlyoke does not set network access: it follows the sandbox.network settings in Claude's own settings files (~/.claude/settings.json and the project's .claude/settings.json). On Windows Claude Code has no Bash sandbox (checked with Claude Code 2.1.319), so ctrlyoke refuses a written sandbox: true before launch instead of letting Claude exit, and skips one inherited from defaults.sandbox with a warning. Containment is declared partial: the Bash sandbox blocks outside writes, but the built-in Write and Edit tools run outside it and follow tool permissions instead, so read-only doesn't stop them either. Verified on macOS with Claude Code 2.1.317: with sandbox: true and allowAll, Bash's outside write failed with EPERM, while Write and Edit changed outside files. See Sandboxing. Claude uses only the last --settings it is given, so a step with sandbox: true and a --settings flag in additionalArgs fails at launch instead of running uncontained.

The permission mode maps to Claude Code flags:

  • dangerouslyAllowAll → --dangerously-skip-permissions. The deny list is ignored.
  • allowAll → --permission-mode bypassPermissions --tools default, plus --disallowedTools
  • auto → --permission-mode auto, plus --allowedTools and --disallowedTools. Auto is available on Opus 4.6+, Sonnet 4.6+, Haiku 5.5 and Fable models on the Anthropic API; eligibility is stricter on Bedrock, Google's Agent Platform and Foundry. with the deny list
  • custom → --allowedTools with the allow list and --disallowedTools with the deny list. In headless runs ctrlyoke also passes --permission-mode dontAsk, which denies any tool that isn't pre-approved. Interactive runs keep Claude's default mode, which asks you in the terminal.
  • none → no permission flags (Claude's own settings, such as ~/.claude/settings.json)

Tool names are translated to Claude's spelling, and arguments are kept: shell and bash become Bash, write becomes Write, and read, edit, multiedit, glob, grep, ls, webfetch and todowrite become Read, Edit, MultiEdit, Glob, Grep, LS, WebFetch and TodoWrite. The default deny list therefore reaches Claude as --disallowedTools Bash(rm:*) Bash(git push:*) …. MCP patterns such as mcp__github__create_issue pass through unchanged.

In headless custom runs, allow rules in Claude's own settings also count as pre-approved, so they can add to your allow list. See Permissions for the modes, the pattern syntax and the default lists.

Notes ​

  • Session IDs are harness-specific. Reuse only Claude sessions with Claude steps.
  • Directories in permissions.trustedExternalRoots are passed to Claude as --add-dir.
  • Hooks and MCP servers are passed per process with --settings and --mcp-config, so ctrlyoke writes nothing to your project's .claude/ folder. See Files ctrlyoke writes.

Usage and rate limits ​

Claude Code reports its 5-hour and 7-day quota windows only to its status line, so ctrlyoke installs a status line command in ~/.claude/settings.json to read them. If you already have a status line, ctrlyoke keeps running yours underneath; see Files ctrlyoke writes.

Because of that, the quota updates only while a Claude session that ctrlyoke started is running, and only while the Claude status line is turned on in Settings → Status Line. Claude Code has no way to ask for the quota on demand, so ctrlyoke: Refresh Harness Usage can't update it. Between runs, ctrlyoke keeps showing the last value along with the time it was read.

Quota percentages appear next to the harness in the harness picker, with the reset time in its tooltip, and on the Stats & Usage settings tab. If a queued step's harness is above usageTracking.warningPercentUsed (80% by default), ctrlyoke warns when the run starts but doesn't stop it. Turn collection off with usageTracking.enabled.

Status line ​

ctrlyoke changes your global Claude Code settings: the first time it runs Claude Code, it points the statusLine key in ~/.claude/settings.json at its own status line command. That is how it reads the quota, and Claude's terminal UI shows the model, context and quota as well. The change stays in place between runs, in every project. If you already had a status line command, ctrlyoke keeps running it underneath.

To undo it, turn Claude Code off in Settings → Status Line. ctrlyoke then puts your original command back, and stops tracking Claude's quota. See Files ctrlyoke writes.

Sign-in problems ​

If your Claude Code sign-in expires during a run, the next step that starts Claude Code fails, and the workflow stops unless errorBehavior retries it. A headless step shows Claude's error in its output; for an interactive step, look at the Terminal tab. Retries fail the same way until you sign in again.

To recover, run claude in a terminal and complete the sign-in, then click Resume in the dashboard to retry the failed step.

From the ctrlyoke CLI, a sign-in failure exits with code 1, not 3. ctrlyoke can't tell an expired sign-in from any other error Claude Code reports, so it counts as a failed step. Code 3 means only that the claude executable wasn't found. See Exit codes, and Harness sign-in for CI runners.

Source-available under the ctrlyoke Commercial License.