Skip to content

harnesses.md

Latest commit

 

History

History
162 lines (125 loc) · 8.63 KB

harnesses.md

File metadata and controls

162 lines (125 loc) · 8.63 KB

Cross-harness capability matrix

claude-agents is a multi-harness plugin marketplace. Source-of-truth lives under plugins/ as Claude Code markdown. Per-harness artifacts are generated by adapters under tools/adapters/.

This file mirrors the capability matrix in tools/adapters/capabilities.py. Edit there; regenerate via make docs.

Supported harnesses

Harness Status Generated paths
Claude Code source-of-truth plugins/, .claude-plugin/marketplace.json
OpenAI Codex CLI supported committed: .agents/plugins/marketplace.json, plugins/*/.codex-plugin/plugin.json; gitignored: .codex/skills/, .codex/agents/
Cursor (2.5+) supported committed: .cursor-plugin/, .cursor/rules/ (curated) — points at source plugins/
OpenCode (sst/opencode) supported gitignored: .opencode/agents/, .opencode/commands/, .opencode/skills/, opencode.json
Gemini CLI supported committed: gemini-extension.json; gitignored: skills/, agents/, commands/ (at extension root)

Capability matrix

Capability Claude Code Codex Cursor OpenCode Gemini
Skills (SKILL.md native) ✅ ✅ ✅ via .claude/ ✅ via .opencode/skills/ ✅ (auto-discovered)
Subagents (markdown native) ✅ TOML format ✅ via .claude/ ✅ (different frontmatter) ✅ (April 2026 spec)
Slash commands ✅ converted to skills ✅ ✅ TOML at commands/
Plugin marketplace ✅ — ✅ (2.5+) — — (direct URL install)
Parallel subagents ✅ ✅ ✅ ✅ ✅ (April 2026)
Per-agent tool allowlist ✅ (tools:) only sandbox_mode only readonly: ✅ (permission: block) ✅ (tools:)
TodoWrite tool ✅ — — ✅ —
Task/Agent spawn tool ✅ name in prose ✅ ✅ (task) @agent syntax
MCP servers ✅ ✅ ✅ ✅ ✅
Lifecycle hooks ✅ — — ✅ (TS plugins) —
Context file CLAUDE.md AGENTS.md (32 KiB cap) AGENTS.md AGENTS.md / ~/.claude/CLAUDE.md GEMINI.md
Context file recommended cap 150 lines / 500 tokens 150 lines / 500 tokens 150 lines / 500 tokens 150 lines / 500 tokens 150 lines / 500 tokens
Skill body hard cap none 8 KB none none none
Tool name case CamelCase (Read) action verbs (no tool vocab) lowercase lowercase (strict) lowercase (Gemini names)
Bare model aliases ✅ (opus/sonnet/haiku) mapped to GPT-5 family use inherit full provider/model-id mapped to gemini-2.5-*

Claude Code native features

Claude Code is the source-of-truth harness. It reads the canonical context file via CLAUDE.md, a symlink to AGENTS.md. Features it supports that other harnesses degrade or lack:

  • Per-agent tool allowlist — tools: frontmatter honored verbatim (Cursor / Codex are coarser; the OpenCode adapter translates this into a permission: block).
  • Task / Agent spawn tool — fan-out parallel subagent execution. (Codex requires naming an agent in prose to delegate.)
  • TodoWrite — native progress tracking. (Not available in Codex / Cursor / Gemini.)
  • Slash-command marketplace — full /plugin install, /plugin marketplace workflow.

Claude-Code-only paths:

  • .claude-plugin/marketplace.json — plugin registry (source of truth)
  • plugins/<name>/.claude-plugin/plugin.json — per-plugin manifest

Graceful degradation

Each adapter handles incompatibilities mechanically — authors don't need to know the per-harness rules to write portable content.

Source pattern Codex Cursor OpenCode Gemini
tools: Read, Grep (agent allowlist) dropped; sandbox_mode = "read-only" heuristic dropped (Cursor doesn't honor) converted to permission: deny block passed through
color: blue (agent) dropped dropped dropped dropped
model: opus (agent) mapped to gpt-5 rewritten to inherit rewritten to anthropic/claude-opus-4-7 mapped to gemini-2.5-pro
TodoWrite in body no equivalent — leave as-is no equivalent — leave as-is works as-is no equivalent
Skill body > 8 KB split into references/details.md passed through passed through passed through
Agent named worker namespaced to <plugin>__worker passed through passed through passed through
Slash command (commands/<x>.md) converted to skill passed through rewritten to .opencode/commands/ TOML at commands/<plugin>/<x>.toml

Output paths (committed vs gitignored)

Native install is lean: only small JSON registries (pointing at the source plugins/) are committed. The large transformed skill/agent trees stay gitignored — regenerate them locally.

Committed:

.claude-plugin/marketplace.json        # SOURCE OF TRUTH
plugins/                               # SOURCE OF TRUTH
AGENTS.md                              # canonical context file
.agents/plugins/marketplace.json       # Codex marketplace registry (source.path: ./plugins/<name>)
plugins/*/.codex-plugin/plugin.json    # per-plugin Codex manifest (skills: ./skills/)
.cursor-plugin/, .cursor/rules/        # Cursor marketplace + curated rules (point at source)
gemini-extension.json                  # Gemini extension manifest (contextFileName: AGENTS.md)

Gitignored (regenerate with make generate):

.codex/skills/, .codex/agents/         # transformed Codex trees (for ~/.codex/skills symlink recipe)
.opencode/agents/, .opencode/commands/, .opencode/skills/, opencode.json
skills/, agents/, commands/            # Gemini trees at extension root (not for OpenCode install)
.copilot/agents/, .copilot/skills/, .copilot/commands/

Native install

  • Codex — npx codex-marketplace add wshobson/agents (or it's auto-discovered as a project marketplace when the repo is the cwd), then install individual plugins. Codex reads SKILL.md straight from plugins/<name>/skills/; skills over the 8 KB cap are truncated by Codex at load. The gitignored .codex/skills/ copies remain for the ~/.codex/skills symlink recipe.
  • Cursor — add the marketplace, then /plugin install <name>. Entries point at source ./plugins/<name>; Cursor reads SKILL.md + .md agents from source directly.
  • Gemini — no one-step-from-URL install (the lean tradeoff). Clone the repo, then make generate HARNESS=gemini and gemini extensions install . (local path).
  • OpenCode — no one-step-from-URL install. Clone the repo, then make install-opencode (runs generate + symlinks .opencode/ → ~/.config/opencode/).

Regenerating

The committed registries point at source; the transformed trees are regenerated on demand. Contributors must run make generate-all before committing source changes — CI fails on drift of the committed registries.

make generate HARNESS=codex
make generate HARNESS=cursor
make generate HARNESS=opencode
make generate HARNESS=gemini
# Or all at once (run before committing source changes):
make generate-all

# Optional global OpenCode install:
make install-opencode
make uninstall-opencode

External Pensyve integrations

The Claude Code marketplace includes Pensyve as an external git-subdir plugin. For generated harnesses, use Pensyve's upstream harness-native integration:

Harness Upstream integration
Claude Code https://github.com/major7apps/pensyve.git, path integrations/claude-code
Codex CLI integrations/codex-plugin
Cursor integrations/cursor
OpenCode integrations/opencode-plugin
Gemini CLI gemini extensions install https://github.com/major7apps/pensyve
Copilot .copilot/ (repo-level) or ~/.copilot/ (global install via make install-copilot)

Global install

OpenCode and Copilot support installing generated artifacts globally for user-level discovery:

make install-opencode    # symlink .opencode/ → ~/.config/opencode/
make uninstall-opencode

make install-copilot     # symlink .copilot/ → ~/.copilot/
make uninstall-copilot

# Force-replace conflicting symlinks:
make install-copilot FORCE=1

Copilot discovers agents from .copilot/agents/ and skills from .copilot/skills/ at the repo level, and from ~/.copilot/agents/ and ~/.copilot/skills/ at the user level. The adapter emits to .copilot/; use make install-copilot for user-level discovery.

See also