agent-harness

Long-running harness for coding agents. Turn any repo into an auto-iterating, multi-agent workspace.

Features

• Multi-agent orchestration – Run multiple agents in parallel with isolated git worktrees
• AI-powered planning – Automatically break down goals into atomic tasks
• Scope-based coordination – Assign agents to different parts of the codebase to prevent conflicts
• Dependency management – Tasks are executed in correct order based on dependencies
• Automatic git integration – Agents commit to separate branches, merged back to main

Installation

pip install agent-harness

Requires Python 3.10+.

Quickstart

cd your-project
agent-harness init          # Interactive setup: define goal, agents, scopes
agent-harness run           # Execute tasks with configured agents
agent-harness status        # View task progress

How It Works

1. agent-harness init – Interactive setup that:

   • Asks for your goal
   • Configures number of parallel agents
   • Defines scope for each agent (e.g., "backend API", "frontend UI")
   • Uses AI to analyze codebase and generate a task plan
   • Saves config to agent_harness.yaml and tasks to feature_list.json

2. agent-harness run – Orchestrator loop that:

   • Creates git worktrees for each agent
   • Assigns runnable tasks (dependencies met) to agents
   • Runs agents in parallel in isolated worktrees
   • Commits and merges changes back to main
   • Handles merge conflicts gracefully

3. agent-harness status – Shows task progress grouped by agent

Configuration

agent_harness.yaml:

features_file: feature_list.json
progress_file: agent-progress.md
init_cmd: bash init.sh
provider: codex              # or "claude"
num_agents: 2
goal: "Build a REST API with user authentication"
agents:
  - id: 1
    scope: "Backend API and database"
  - id: 2
    scope: "Authentication and middleware"

feature_list.json:

{
  "tasks": [
    {
      "id": "task_001",
      "title": "Set up project skeleton",
      "description": "Create basic project structure",
      "status": "todo",
      "assigned_agent": 1,
      "dependencies": [],
      "files_touched": ["src/main.py", "requirements.txt"],
      "verification": "python src/main.py runs without error",
      "notes": ""
    }
  ]
}

Providers

All providers run in YOLO mode (autonomous, no permission prompts) for seamless agent execution:

Codex Configuration

# Planner (gpt-5 with high reasoning)
codex exec "<prompt>" \
  --model gpt-5 \
  -c model_reasoning_effort="high" \
  -c approval_policy="never" \
  -c sandbox_mode="danger-full-access"

# Executor (gpt-5-codex-max with xhigh reasoning)
codex exec "<prompt>" \
  --model gpt-5-codex-max \
  -c model_reasoning_effort="xhigh" \
  -c approval_policy="never" \
  -c sandbox_mode="danger-full-access"

Claude Configuration

claude --dangerously-skip-permissions --model claude-opus-4-5 -p "<prompt>"

First-time setup: Run claude --dangerously-skip-permissions interactively once and accept the warning.

Gemini Configuration

gemini --yolo -m gemini-3-pro-preview -p "<prompt>"

Toggle in interactive mode: Press Ctrl+Y to enable/disable YOLO mode.

Set provider via --provider flag on init or in config.

Architecture

agent_harness/
├── cli.py           # CLI commands (init, run, status)
├── config.py        # Configuration loading/saving
├── orchestrator.py  # Multi-agent coordination
├── git_coord.py     # Git worktree management
├── scaffold.py      # File scaffolding
├── state.py         # Task and progress I/O
└── agents/
    ├── base.py      # BaseAgent abstract class
    ├── cli_agent.py # Agent using CLI tools
    └── planner.py   # AI planner for task generation

Multi-Agent Workflow

1. Each agent gets its own git branch (agent/1, agent/2, etc.)
2. Agents work in isolated worktrees under .agent_worktrees/
3. Before each step, agents sync with main branch
4. After completing a task, changes are merged back to main
5. Merge conflicts are detected and tasks marked as blocked

License

MIT