Harness Config

This is the quick reference for teams that use more than one coding-agent harness. It separates two concerns:

1. The harness CLI controls a session: prompt, working directory, model, permissions, output, and resume behavior.
2. Tuff manages reusable project capabilities: skills, tools, hooks, and workflows, then emits them into the selected harness layout.

The upstream CLIs change quickly. Treat this page as a workflow map and run <command> --help for the exact version installed on your machine. The links in the last section are the authoritative references.

Quick Comparison

Harness	Start	Project config
Claude Code	claude	CLAUDE.md · .claude/
Codex CLI	codex	AGENTS.md · .agents/
Cursor CLI	cursor-agent	.cursor/rules/ · .cursor/commands/
OpenCode	opencode	AGENTS.md · .opencode/

Target-folder map

Use this map before adding a file manually. A target is project-local unless the path begins with ~; project-local files are normally committed, while local settings and user state should stay out of version control.

Claude Code

Intent	Target
Shared instructions	CLAUDE.md or .claude/CLAUDE.md
Personal instructions	CLAUDE.local.md or .claude/settings.local.json
Skills and commands	.claude/skills/<name>/SKILL.md .claude/commands/<name>.md
Agents and rules	.claude/agents/ .claude/rules/
MCP and hooks	.mcp.json .claude/settings.json
User config	~/.claude/ and ~/.claude.json

Codex CLI

Intent	Target
Shared instructions	AGENTS.md
Local override	AGENTS.override.md in the relevant directory
Skills	.agents/skills/<name>/SKILL.md
MCP and runtime config	~/.codex/config.toml or CODEX_HOME

Cursor CLI

Intent	Target
Shared rules	.cursor/rules/<name>.mdc
Reusable commands	.cursor/commands/<name>.md
CLI permissions	.cursor/cli.json or ~/.cursor/cli-config.json
MCP	mcp.json

OpenCode

Intent	Target
Shared instructions	AGENTS.md or project rules in .opencode/
Skills	.opencode/skills/<name>/SKILL.md
Commands and agents	.opencode/commands/ .opencode/agents/
Project config	opencode.json or opencode.jsonc
User config	~/.config/opencode/

Tuff is the cross-harness layer: use tuff.toml and tuff.lock as the source of truth, then emit adapter-specific files into .agents/, .claude/, or another supported target.

What Tuff emits

Tuff keeps the capability source and lock metadata independent from the harness output:

tuff.toml                 # capability manifest / source declaration
tuff.lock                 # tracked identity, scope, agent, and baseline
.agents/                   # open-agents / Codex-compatible output
  skills/<id>/SKILL.md
.claude/                   # Claude-oriented output
  skills/<id>/SKILL.md
  commands/<id>.md

The exact emitted paths depend on the capability type and adapter. Inspect them with tuff list, tuff status, or tuff generate report instead of assuming that every harness has the same layout.

Flag translation

The same operational intent has different spellings. Do not copy a flag from one harness to another without checking its safety model.

Intent	Claude Code	Codex CLI	Cursor CLI	OpenCode
Start interactive	claude	codex	cursor-agent	opencode
Non-interactive	-p, --print	exec / e	-p, --print	run
Select working directory	run from directory; --add-dir adds access	--cd, -C; --add-dir	run from directory	--dir on attach; run from project directory
Continue latest	-c	exec resume --last or interactive resume	cursor-agent resume	--continue, -c
Resume by id	--resume, -r	exec resume <id>	resume [thread id]	--session, -s
Choose model	--model	--model / config	--model	--model, -m
Add another directory	--add-dir	--add-dir	use project context / permissions config	use config and project discovery
Structured output	--output-format json or stream-json	--json and optional --output-last-message	--output-format json	--format json for run
Permission posture	--permission-mode plan / acceptEdits; avoid bypass by default	--ask-for-approval on-request plus --sandbox workspace-write	approval prompts; headless writes need --force	configure permission; --auto auto-approves
Session-only instructions	--append-system-prompt or --settings	-c key=value and prompt	prompt text	OPENCODE_CONFIG_CONTENT or prompt

Safety note: --dangerously-skip-permissions, Codex --yolo, Cursor --force, and OpenCode --auto can materially increase write or command execution authority. Prefer the narrowest permission mode that completes the task, especially in CI.

Common workflows

1. Start a task with the correct project context

# These examples use terminal frames so they read like a macOS/Linux shell.

# Claude Code
claude --permission-mode plan "Inspect the release workflow and propose changes"

# Codex CLI
codex --cd . --ask-for-approval on-request --sandbox workspace-write \
  "Inspect the release workflow and propose changes"

# Cursor CLI
cursor-agent -p "Inspect the release workflow and propose changes" \
  --output-format text

# OpenCode
opencode run "Inspect the release workflow and propose changes"

Expected target: the current repository, its instruction file, and the harness-specific capability folders discovered from that repository.

2. Add a capability with Tuff

tuff init
tuff agent add open-agents
tuff agent add claude

# Create a new capability for both harnesses
tuff create skill release-check -a open-agents -a claude

# Adopt an existing project capability without rewriting its content
tuff add --agent open-agents .agents/skills/release-check

# Inspect what is tracked and where it was emitted
tuff list
tuff status
tuff generate report --output docs/tuff-report.md

Use tuff add skill <source> --agent <id> when the source type is known, or the untyped tuff add <source> form when Tuff should infer it. For a harness-native hook fragment:

tuff add hook ./claude-session-start --agent claude --hook-file settings.json

3. Detect and reconcile drift

tuff list
tuff diff <capability-id>
tuff diff <capability-id> --upstream
tuff update <capability-id> --check
tuff update <capability-id>
tuff check --json

Interpretation:

• list is the fast inventory and drift view.
• diff shows local changes against Tuff’s pristine baseline.
• diff --upstream compares a Git-sourced capability with its latest source.
• update --check previews reconciliation without writing.
• update accepts intentional local edits or merges upstream changes, depending on the source.
• check --json is the CI gate.

4. Remove safely

# Remove generated files, refusing modified files by default
tuff delete <id> -a claude

# Remove generated files even when they changed
tuff delete <id> -a claude --force

# Stop managing files but leave them in place
tuff untrack <id> -a claude

# Remove an adapter registration only; capabilities remain untouched
tuff agent remove claude

Use delete when Tuff owns the generated files. Use untrack when the files should remain available to the harness. agent remove is configuration-only; it is not a cleanup command.

Operations reference

Safe defaults

• Start from the repository root or pass the harness directory flag.
• Commit shared instruction files and project capability definitions.
• Keep user state, credentials, local settings, and session transcripts out of the repository.
• Use plan / approval-on-request / workspace-write modes for exploratory work.
• Use JSON output in automation and preserve the process exit code.
• Run tuff check --json before release or deployment automation.
• Review generated paths with tuff status after adding or changing an adapter.

Project versus global scope

Project scope is for reproducible team behavior. Global scope is for personal defaults or organization-wide local setup. Tuff follows the same distinction:

tuff init                 # project state
tuff init --global        # user/global state
tuff add skill ./pack     # project capability
tuff add skill ./pack --global
tuff agent set-default claude
tuff agent set-default claude --global

When project and global capabilities share an id, the project copy wins. Use tuff status to find shadowing and override warnings.

For the Tuff command and flag reference, see CLI Reference. For concepts and side effects, see Lifecycle & Drift Detection, Diffing & Updates, and Scopes & Overrides.

Official references

• Claude Code CLI reference, settings, and .claude directory
• Codex CLI command reference and AGENTS.md discovery
• Cursor CLI usage, parameters, and project rules
• OpenCode CLI, configuration, and skills