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 | Listed under | 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 in Settings → Harnesses (⌘, then the Harnesses tab, or Harnesses in the ⌘K palette). The tab has two panes:
- On the left, every harness grouped as Coding agents, LLM APIs and Built-in, each with its logo and a status dot: green when detected, red when not, amber while checking, grey when disabled. A harness with a newer CLI release shows an arrow, and the numbers show how many of its models are switched on out of the total.
- On the right, the selected harness: its version (or why it wasn’t found) and an update badge when there’s a newer release, how many pipeline steps use it, a Docs link, Configure, reset (↺) or delete, the enable switch, its description, a preview of the command line it runs, and its Models list.
In the Models list each model has an on/off switch, and Make default (shown when you hover a model) makes it the default. Switched-off models stay in the list but aren’t offered in the step, template and Build with AI model pickers. See Models.
The built-in catalog
Section titled “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.
How a CLI harness runs
Section titled “How a CLI harness runs”For each attempt of an agent step on a CLI harness, Jimothy:
- Renders the step prompt (and system prompt) from its template.
- If the harness has no System prompt arguments, prepends the system prompt to the prompt, separated by a
---line. - If the prompt is delivered by file (or any argument uses
{{promptFile}}), writes it toruns/<run-id>/tmp/prompt-<id>.mdin the data folder. - Builds the argument list from the harness’s argument template (see Custom harnesses), adding model, system-prompt and subagent arguments only when they apply.
- Logs the command line to the step log as
$ command args …(the prompt shows as<prompt>, subagents as<subagents>, long arguments are shortened). - 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
Section titled “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 |
{{steps.<id>.output}} is always the complete output. The run page shows the last 20,000 characters of a longer one (the start is replaced with …[N earlier chars omitted], because conclusions come at the end), with Show the full output to load the rest.
Models
Section titled “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
Section titled “Auto-detection”Jimothy checks every enabled harness at startup, whenever you save or enable a harness, and when you click Re-detect in Settings → Harnesses.
- CLI harnesses run
commandwith 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 harness 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 harness showsSet 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)
Section titled “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:
- Settings → General → Extra PATH entries (one per line; searched first).
- 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. - The
PATHthe app itself was started with. - 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.
Updates
Section titled “Updates”When it detects an installed CLI, Jimothy also looks up its latest release: on npm or PyPI when the CLI was installed with npm, pipx or uv, otherwise from the harness’s release source (for example its GitHub releases). If a newer version exists, the harness shows a badge such as 2.3.0 available. When Jimothy can tell how the CLI was installed, clicking the badge copies the update command (npm install -g <package>@latest, brew upgrade <name>, brew upgrade --cask <name>, pipx upgrade <name> or uv tool upgrade <name>); otherwise update it the way you installed it.
After you update the CLI in a terminal, the badge clears by itself: Jimothy re-reads the installed version of each outdated harness when you switch back to the app, and whenever you open the Harnesses tab.
Each harness shows a logo. Built-in harnesses and CLIs Jimothy recognises by their command get their brand logo automatically, and API harnesses get one from their base URL (OpenRouter, Ollama, LM Studio, DeepSeek, Qwen, Mistral, Kimi, xAI, Groq) or provider. Anything else shows a plain robot. Logos are bundled with the app, so nothing is downloaded. To choose one yourself, use Logo in the harness editor; see Custom harnesses.
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
Section titled “Enabling, disabling, resetting and deleting”| Action | How | Effect |
|---|---|---|
| Disable | The switch at the top right of the harness | 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 | Configure (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 at the top of the tab | Creates a custom CLI or API harness. See Custom harnesses. |