Skip to content

docs: Clarify harness identifiers (claude vs claude-code) and dedupe run-cloud flags #689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hongyi-chen merged 2 commits into from
Sep 8, 2026
Merged

docs: Clarify harness identifiers (claude vs claude-code) and dedupe run-cloud flags #689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7de40b8
Clarify harness identifiers and dedupe run-cloud harness flags
hongyi-chen Sep 4, 2026
b6ce52e
Merge branch 'main' into docs/harness-identifiers
hongyi-chen Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/content/docs/factories/factory-as-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ harness:

### `agentDefaults.harness`

The harness and model that runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude` (alias `claude-code`), `codex`, or `gemini` — the values the definition schema validates. For what each harness does and which ones your team can run, see [supported harnesses](/platform/harnesses/).
The harness and model that runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude`, `codex`, or `gemini` — the values the definition schema validates. `claude-code` is also accepted as an alias for `claude`; prefer `claude`, the canonical [harness identifier](/platform/harnesses/#harness-identifiers) that the CLI and the Agent API use for the same harness. For what each harness does and which ones your team can run, see [supported harnesses](/platform/harnesses/).

```yaml
harness:
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/platform/harnesses/claude-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/au

* **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Claude Code**.
* **{VARS.WEB_APP}** - On the new run or new schedule pane, choose **Claude Code** in the **Harness** field. A **Claude Code auth secret** field appears below it; pick one of your stored Anthropic secrets.
* **API and SDK** - Set the agent config `harness` to `claude` and the Anthropic secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/).
* **API and SDK** - Set the agent config `harness` to `claude` — the [harness identifier](/platform/harnesses/#harness-identifiers) is `claude`, not `claude-code` — and the Anthropic secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/).

## Related pages

Expand Down
12 changes: 11 additions & 1 deletion src/content/docs/platform/harnesses/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,17 @@ On the new run or new schedule pane, choose the harness in the **Harness** field

### API and SDK

Set the `harness` field on the agent config. See the [API reference](/reference/api-and-sdk/) for the exact field names.
Set the `harness` field on the agent config to one of the [harness identifiers](#harness-identifiers) below. See the [API reference](/reference/api-and-sdk/) for the exact field names.

## Harness identifiers

Surfaces that take the harness as a string all use the same identifiers: `oz` for the Warp Agent, `claude` for Claude Code, and `codex` for Codex. Write `claude` for Claude Code — not `claude-code`:

* **API and SDK** — the agent config's `harness.type` accepts `oz`, `claude`, or `codex`.
* **CLI** — `oz agent run-cloud --harness` accepts the same identifiers, plus `claude-code` as an alias for `claude`.
* **Factory definition files** — [`harness.type`](/factories/factory-as-code/#agentdefaultsharness) accepts the same identifiers, plus the `claude-code` alias.
Comment on lines +61 to +65

@warp-for-oss warp-for-oss Bot Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [IMPORTANT] This list says factory definition files accept only the shared identifiers plus the alias, but factory-as-code.mdx still documents gemini as schema-validated; include that factory-only value or readers get conflicting accepted-value guidance.

Suggested change
Surfaces that take the harness as a string all use the same identifiers: `oz` for the Warp Agent, `claude` for Claude Code, and `codex` for Codex. Write `claude` for Claude Code — not `claude-code`:
* **API and SDK** — the agent config's `harness.type` accepts `oz`, `claude`, or `codex`.
* **CLI** — `oz agent run-cloud --harness` accepts the same identifiers, plus `claude-code` as an alias for `claude`.
* **Factory definition files** — [`harness.type`](/factories/factory-as-code/#agentdefaultsharness) accepts the same identifiers, plus the `claude-code` alias.
Surfaces that take the harness as a string use `oz` for the Warp Agent, `claude` for Claude Code, and `codex` for Codex. Write `claude` for Claude Code — not `claude-code` — unless the surface explicitly accepts that alias:
* **API and SDK** — the agent config's `harness.type` accepts `oz`, `claude`, or `codex`.
* **CLI** — `oz agent run-cloud --harness` accepts the same identifiers, plus `claude-code` as an alias for `claude`.
* **Factory definition files** — [`harness.type`](/factories/factory-as-code/#agentdefaultsharness) accepts `oz`, `claude`, `codex`, or `gemini`, plus `claude-code` as an alias for `claude`.

@warp-factories warp-factories Bot Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed — factory definition files now list gemini alongside the shared identifiers, matching factory-as-code.mdx.


Where the alias is accepted, it selects the same Claude Code harness as `claude`. Everywhere else — including the API — only the canonical identifiers are valid, so prefer them in anything you script, sync, or store.

## Related pages

Expand Down
5 changes: 1 addition & 4 deletions src/content/docs/reference/cli/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,13 +273,10 @@ oz agent run-cloud \
* `--host <WORKER_ID>` — run on a specific self-hosted worker instead of Warp-hosted infrastructure.
* `--attach <PATH>` — attach an image file to the agent query. Can be repeated (maximum 5).
* `--computer-use` / `--no-computer-use` — enable or disable [Computer Use](/agents/capabilities/computer-use/) for this run.
* `--harness <HARNESS>` — choose the execution harness for the run. Defaults to `oz` (Warp Agent). Set `claude` or `codex` to run [Claude Code or Codex as a cloud agent](/platform/harnesses/).
* `--harness <HARNESS>` — choose the [execution harness](/platform/harnesses/) for the run: `oz` (default, the Warp Agent), `claude` (Claude Code), or `codex` (Codex). `claude-code` is accepted as an alias for `claude`. See [harness identifiers](/platform/harnesses/#harness-identifiers).
* `--claude-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Claude Code harness. Only valid with `--harness claude`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/).

@warp-for-oss warp-for-oss Bot Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [IMPORTANT] Now that the previous bullet documents claude-code as an accepted alias, this auth-secret line should not say the flag is only valid with --harness claude.

Suggested change
* `--claude-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Claude Code harness. Only valid with `--harness claude`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/).
* `--claude-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Claude Code harness. Use with `--harness claude` or the `--harness claude-code` alias. See [Third-party cloud agent authentication](/platform/harnesses/authentication/).

@warp-factories warp-factories Bot Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed — the auth-secret bullet now notes it also applies with the --harness claude-code alias.

* `--codex-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/secrets/) that authenticates the Codex harness. Only valid with `--harness codex`. See [Third-party cloud agent authentication](/platform/harnesses/authentication/).
* `--file <PATH>` (`-f`) — load run configuration from a YAML or JSON file.
* `--harness <HARNESS>` — choose the [execution harness](/platform/harnesses/) for the run: `oz` (default, Warp's built-in agent infrastructure), `claude` (Claude Code), or `codex`.
* `--claude-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/harnesses/authentication/) that authenticates the Claude Code harness. Only valid with `--harness claude`.
* `--codex-auth-secret <NAME>` — name of the [Warp-managed secret](/platform/harnesses/authentication/) that authenticates the Codex harness. Only valid with `--harness codex`.

To run a third-party harness, first store the provider credential as a Warp-managed secret, then pass it with the matching flag:

Expand Down
Loading