Skip to content

Supported harnesses

A harness is the CLI environment a coding agent runs in. ai_stp does not replace the harness and does not call models: it helps assemble a checkable setup for one target, and only that harness's provider writes the final state.

MVP status

Harness MVP status What is available What to remember
Claude Code beta passports, compatibility, setup assembly, provider plan ships in the open beta with the other six harnesses
Codex beta passports, compatibility, setup assembly, provider plan ships in the open beta with the other six harnesses
Grok Build beta passports, compatibility, setup assembly, provider plan ships in the open beta with the other six harnesses
Pi beta passports, compatibility, setup assembly, provider plan ships in the open beta with the other six harnesses
OpenCode beta passports, compatibility, setup assembly, provider plan ships in the open beta with the other six harnesses
Cursor beta passports, compatibility, setup assembly, provider plan a plugin pack is recognised by its .cursor-plugin manifest
Antigravity beta passports, compatibility, setup assembly, provider plan its configuration lives inside ~/.gemini rather than a home of its own
undefined limited mode reading, import, local checks automatic installation is not considered safe

What "supported" means

Support in ai_stp is made of levels. A harness can pass one level and not yet be ready for the next.

Level What is checked Why it matters to you
Detection the CLI knows which target it is looking at so a setup is not applied to the wrong place
Compatibility components declare which harness they support so the obviously unsuitable is filtered out
Projection a setup can be turned into a native structure so files and settings land in the right format
Provider plan the provider builds a plan to change the target so you see the diff before anything is applied
Apply the provider applies the change and records it so there is a rollback and a checkable result

Claude Code, Codex, Grok Build, Pi, OpenCode, Cursor, and Antigravity ship together. Find a setup, check compatibility, see the plan, and apply through the provider. Missing evidence is labelled not_verified; it does not drop a harness from the product.

This mode exists so an object is not lost when the harness is unknown. It is fine for reading, import and local analysis, but not for confident automatic installation.

Why a setup belongs to one harness

Because the same words mean different files, permissions and events in different CLIs. A skill for Codex and a skill for Claude Code may mean something similar and still have different native surfaces. So a setup is created for one harness, and moving it means an explicit new version or an adaptation.

What lands on disk for the seven harnesses

ai_stp does not copy files into a target. The assembler builds a native package; the provider writes it. Exact paths for a machine come from ai-stp component discover --json (source_path, layout_source) and from the provider plan. The kinds that discovery will look for are:

Kind Claude Code Codex Grok Build
instruction global and project global and project not a declared native instruction layout
skill global and project shared skill (including .agents/skills) global and project
mcp global and project names inside the settings file (config.toml) when the mcp_servers key is present names inside config.toml when the key is present
hook not a top-level declared layout in the discovery matrix project: .codex/hooks.json, or hooks/hooks.json inside a proven plugin global and project
command global and project global command/prompt shared command, global
agent global and project project: .codex/agents not a declared native agent layout
plugin global and project; a pack is a plugin only through .claude-plugin/plugin.json plugin root, skill, and hooks-directory; pack through .codex-plugin/plugin.json global and project; plugins/marketplaces is not a plugin
setting global and project global and project (config.toml) global and project (config.toml)

A directory under plugins/ without a manifest from a supported harness is not a plugin. CODEX.md is not an official Codex instruction layout; discovery reports it as unsupported_manifest and points at AGENTS.md.

Shared .agents/skills belong to no single harness and come back with harness_id=null.

After apply, confirm with:

ai-stp target status --project <id> --harness <id> --json
ai-stp target diff --project <id> --harness <id> --json

Official harness documentation

These are the vendors' own docs, not ai_stp pages. Layouts ai_stp will act on are still only those component discover returns with a layout_source.

Harness Official documentation
Claude Code Claude Code docs
Codex ChatGPT / Codex docs (native instruction file: AGENTS.md)
Grok Build xAI Build docs
Pi Pi docs
OpenCode OpenCode docs
Cursor Cursor docs
Antigravity Antigravity docs

If a classification is uncertain, show the layout_source field from component discover. Do not invent a path because a neighbouring harness uses one.

Choosing a target

  1. Run ai-stp doctor --json.
  2. Check which harness was detected: ai-stp toolchain harnesses --json.
  3. Open the setup or component in the catalog.
  4. Compare harness support and the trust line.
  5. Read the provider plan before applying.
ai-stp doctor --json
ai-stp toolchain harnesses --json
ai-stp toolchain harness-capabilities --json

For the MVP

If you are unsure, start with Claude Code, Codex, or Grok Build. For beta lines, keep the install plan and do not delete the backup until you have checked the result.