coding-agent-harness 0.1.0
Lightweight long-running harness for coding agents
Requires Python: >=3.10
Keywords: ai, agents, coding, automation, llm, claude, codex, gemini

# 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

```bash
pip install agent-harness
```

Requires Python 3.10+.

## Quickstart

```bash
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`:
```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`:
```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:

| Provider | Planner Model | Executor Model | YOLO Mode |
|----------|--------------|----------------|-----------|
| **codex** | gpt-5 (high reasoning) | gpt-5-codex-max (xhigh reasoning) | `approval_policy=never`, `sandbox_mode=danger-full-access` |
| **claude** | claude-opus-4-5 | claude-opus-4-5 | `--dangerously-skip-permissions` |
| **gemini** | gemini-3-pro-preview | gemini-3-pro-preview | `--yolo` |

### Codex Configuration
```bash
# 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
```bash
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
```bash
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