Start here

Install and configure

Clone, run one command, edit one JSON file. An agent can do all of it from the README; inspect support and configuration ownership before syncing.

Claude Code and Codex are integration targets. Check the versioned compatibility catalog ; planned in it: cursor, grok.

Install

On a fresh machine, install brings in the tools and then links the harness in:

Fresh machinesh

git clone https://github.com/JakeSelby/agent-harness.git ~/repos/agent-harness
cd ~/repos/agent-harness
bin/harness install
# Homebrew packages, VS Code + extensions, Claude Code, Codex, gh, then sync

Link an existing setup

If Claude Code, Codex and VS Code are already installed, skip straight to the sync. Unmanaged files require explicit adoption; modified owned files produce conflicts and are preserved.

Tools already installedsh

bin/harness sync --dry-run
bin/harness sync

Configure

Copy config.example.json to ~/.config/agent-harness/config.json, put your name and stances in it, and run bin/harness sync again. Keep personal identity outside the checkout. Each stance key selects one policy projected into the runtimes you enable.

config.example.jsonjson

{
  "identity": {
    "name": "Your Name",
    "pronouns": "they/them",
    "role": "One line about what you do, so the agent pitches its answers right.",
    "github": "your-github-handle",
    "timezone": "UTC",
    "expertise": "expert"
  },
  "stances": {
    "licensing": "permissive-commercial",
    "build-vs-buy": "capability-ceiling",
    "commits": "conventional-attributed",
    "plan-ceremony": "review-card",
    "delegation": "tiered",
    "testing": "required",
    "autonomy": "execute",
    "cost": "balanced",
    "voice": "scannable"
  },
  "permissions": "inherit",
  "permissions_bypass_acknowledged": false,
  "plan_allow_tools": [],
  "vscode": {
    "manage": true
  },
  "codex": {
    "manage": true
  },
  "claude": {
    "manage": true
  },
  "telemetry": {
    "export": "off"
  },
  "governance": {
    "provider": "none",
    "jev": {
      "mode": "off",
      "modes": {},
      "state_fields": []
    }
  },
  "primitive_roots": [],
  "remote_control": {
    "folders": [],
    "spawn": "worktree",
    "permission_mode": "default",
    "keep_awake": false
  },
  "integrations": {
    "architecture-viewer": {
      "implementation": "builtin"
    }
  },
  "integration_adapters": {}
}

Each key under stances is a dimension; the value names the variant that loads on every turn.

autonomy: ask · confirm-writes · execute — default execute
build-vs-buy: capability-ceiling · off — default capability-ceiling
commits: as-you-go · conventional-attributed · conventional · off — default conventional-attributed
cost: balanced · frugal · max — default balanced
delegation: off · session-model · tiered — default tiered
licensing: off · open-source · permissive-commercial — default permissive-commercial
plan-ceremony: light · review-card — default review-card
testing: off · pragmatic · required — default required
voice: answer-card · off · scannable — default scannable

Session stance choices are explicit and scoped; they never grant native permissions. Inspect effective selections with harness stances --json.

Check and undo

After the syncsh

bin/harness doctor    # versions, logins, links, drift
bin/harness diff      # what changed since the last sync
bin/harness uninstall # put everything back

In a session, /context lists the harness rules and the selected stances; /hooks lists the hooks. The sync model and settings ownership pages say exactly what the sync touches and what it never will.