Harnesses overview

A harness is the thing that actually executes an agent step. Every agent step in a pipeline picks a harness, an optional model and a prompt. Jimothy renders the prompt, hands it to the harness in the run’s workspace, streams what comes back into the step log, and captures the final output (plus cost and tokens when the harness reports them).

There are three kinds of harness:

Kind	Shown on the Harnesses page as	What it does
cli	Coding agents	Spawns a local command-line agent (Claude Code, Codex, Aider, …) in the run’s workspace. The agent can read and edit files and run commands.
api	LLM APIs	Calls an LLM API directly: one request, one answer, no tools and no file access. Good for triage, specs, summaries and reviews of text you put in the prompt.
mock	Built-in	The Simulator: a fake agent that needs no installation or key.

You manage harnesses on the Harnesses page (sidebar → Harnesses). Each harness card shows its detection status, a Docs link, a command preview, the first six models (the default model is highlighted), how many pipeline steps use it, and an enable/disable toggle.

The built-in catalog

Jimothy ships these harnesses preconfigured. All of them can be edited (CLI flags change often) and reset to their defaults.

Harness	Id	Command	Prompt via	Output format	Model flag	Model list source	Cost / tokens
Claude Code	claude-code	claude	stdin	claude-stream-json	--model {{model}}	Anthropic API	cost + tokens
OpenAI Codex CLI	codex	codex	stdin	codex-json	--model {{model}}	codex debug models	tokens
Gemini CLI	gemini-cli	gemini	argument	text	--model {{model}}	Gemini OpenAI-compatible API	—
Cursor Agent	cursor-agent	cursor-agent	argument	text	--model {{model}}	cursor-agent models	—
GitHub Copilot CLI	copilot-cli	copilot	argument	text	--model {{model}}	none	—
Aider	aider	aider	file	text	--model {{model}}	none	—
OpenCode	opencode	opencode	argument	text	--model {{model}}	opencode models	—
Pi	pi	pi	stdin	pi-json	--model {{model}}	pi --list-models	cost + tokens
Amp	amp	amp	stdin	text	none	none	—
Goose	goose	goose	argument	text	none	none	—
Claude API	anthropic-api	—	—	—	—	Anthropic API	tokens
OpenAI-compatible API	openai-compatible	—	—	—	—	GET {baseUrl}/models	tokens (when the server reports usage)
Simulator	simulator	—	—	—	—	—	simulated

“Cost” means a dollar amount reported by the harness itself. Jimothy does not price tokens on its own, so harnesses that report only tokens (Codex, the API harnesses) contribute tokens but $0 to run cost. Plain-text harnesses report neither.

Unattended by default

Most CLI harnesses are configured to run without asking for permission: Claude Code with --dangerously-skip-permissions, Codex with --full-auto, Gemini with --yolo, Cursor with --force, Copilot with --allow-all-tools, Aider with --yes-always, Amp with --dangerously-allow-all. Agents run with your user’s permissions. Point triggers only at trackers where you trust who can create or label issues, prefer worktree workspaces, and put a human approval gate before anything that pushes or deploys. See Data & security.

How a CLI harness runs

For each attempt of an agent step on a CLI harness, Jimothy:

1. Renders the step prompt (and system prompt) from its template.
2. If the harness has no System prompt arguments, prepends the system prompt to the prompt, separated by a --- line.
3. If the prompt is delivered by file (or any argument uses {{promptFile}}), writes it to runs/<run-id>/tmp/prompt-<id>.md in the data folder.
4. Builds the argument list from the harness’s argument template (see Custom harnesses), adding model, system-prompt and subagent arguments only when they apply.
5. Logs the command line to the step log as $ command args … (the prompt shows as <prompt>, subagents as <subagents>, long arguments are shortened).
6. Spawns the process in the run’s workspace with the step’s environment, writes the prompt to stdin if the harness uses stdin, and parses stdout line by line with the harness’s output format.

The step fails if the process can’t start, exits non-zero, times out, is cancelled, or the structured output reports an error. On failure, the last five stderr lines are appended to the error message.

Cancelling a run or hitting a step timeout sends SIGTERM to the whole process group, then SIGKILL five seconds later, so child processes the agent started are killed too.

Output formats

The output format decides how stdout is interpreted and what counts as the step’s output (the value later steps read as {{steps.<id>.output}}).

Format	Editor label	Log lines	Step output	Cost / tokens
text	Plain text	Every stdout line as-is	All of stdout, with ANSI colour codes stripped and trimmed	none
claude-stream-json	Claude Code stream-json	Session info, assistant text, thinking, tool calls (with the command, file path, pattern, URL or query), tool results, final result summary	The result field of the final result event, or the last assistant text	total_cost_usd, input/output/cache tokens
codex-json	Codex exec –json	Thread id, agent messages, reasoning, $ command executions with exit codes and output, file changes, MCP tool calls, web searches, turn totals	The last agent message	tokens summed over turns (input, output, cached input)
pi-json	Pi –mode json	Session info, assistant text, thinking, tool calls and results, final turn/cost summary	The last assistant message	summed cost and tokens

Stored step output is capped at the last 20,000 characters (the start is replaced with …[N earlier chars omitted]), because conclusions come at the end.

Models

Every harness has a model list and a default model. A step can pick one of those models, type any other model id, or leave the model on Default. The model flag is only added when a model is actually chosen, so an empty default lets the CLI use its own configured model. See Models.

Auto-detection

Jimothy checks every enabled harness at startup, whenever you save or enable a harness, and when you click Re-detect on the Harnesses page.

• CLI harnesses run command with the Version check args (default --version), with a 15 second timeout. Exit code 0 means available, and the first line of output (up to 80 characters) is shown as the version. If the executable is missing, the card shows "<command>" not found on PATH.
• API harnesses are available when an API key is set on the harness, the key environment variable is set, or the base URL points at localhost / 127.0.0.1 (local servers like Ollama don’t need a key). Otherwise the card shows Set an API key or <ENV_VAR>.
• The Simulator is always available.

A green dot (●) next to a harness in the step editor’s Harness menu means it was detected; a hollow dot (○) means it was not. Steps can still select an undetected harness, but the editor warns you, and the run will fail if the command really can’t be started.

Where Jimothy looks for CLIs (PATH)

GUI apps on macOS and Linux don’t inherit your shell’s PATH, so a CLI installed with Homebrew, npm -g, pipx or similar would normally be “not found”. Jimothy works around this. The PATH given to every harness, shell step and detection check is built from, in order:

1. Settings → Execution → Extra PATH entries (one per line; searched first).
2. Your login-shell PATH. At startup Jimothy runs $SHELL -ilc 'printf … "$PATH"' (falling back to /bin/bash) with an 8 second timeout and reads the result.
3. The PATH the app itself was started with.
4. Common install locations: ~/.local/bin, ~/.claude/local, ~/.npm-global/bin, ~/.bun/bin, ~/.cargo/bin, ~/.opencode/bin, ~/.volta/bin, /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin.

Duplicates are removed. If a CLI is still not found, add its directory to Extra PATH entries, or set Command on the harness to an absolute path.

Jimothy also sets CI=1 (unless CI is already set), NO_COLOR=1, FORCE_COLOR=0 and GIT_TERMINAL_PROMPT=0 for child processes so CLIs behave non-interactively. See Environment variables.

Enabling, disabling, resetting and deleting

Action	How	Effect
Disable	Toggle on the harness card	Left out of the step editor’s harness menu and of detection. Steps that still use it fail with Harness X is disabled — enable it on the Harnesses page or pick another harness.
Configure	Pencil button (not available for the Simulator)	Opens the harness editor. Saving stores your version of the harness and re-runs detection for it.
Reset to built-in defaults	↺ button on built-in harnesses	Discards everything you changed on that harness, including a stored API key and the disabled flag.
Delete	Trash button (custom harnesses only)	Removes the harness. Steps using it fail until you pick another harness. Built-in harnesses can’t be deleted, only disabled.
Add harness	Add harness in the page header	Creates a custom CLI or API harness. See Custom harnesses.

Note

Once you save a built-in harness, your saved copy takes precedence field by field over the shipped definition. If a later version of Jimothy changes the built-in flags, your edited harness keeps your values until you reset it.

Claude CodeThe default coding harness: stream-json, cost, subagents.

Custom harnessesWire up any CLI with an argument template.

API harnessesClaude API, OpenAI, OpenRouter, Ollama, LM Studio, vLLM.

ModelsModel lists, defaults, fetching the latest models.