claude-harness

# Claude Harness

A self-hosted WebUI that orchestrates fully autonomous coding using [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Point it at a GitHub repo, describe what you want built, and Claude works through the project iteratively — creating issues, writing code, running tests, and committing results.

Designed for large projects that take many iterations. Claude maintains context across sessions via a living `CLAUDE.md` knowledge base, GitHub Issues for task tracking, and structured handoff files.

## Features

- **Project kick-off** with Q&A — Claude asks clarifying questions before starting
- **Automatic planning** — creates GitHub Issues as a task breakdown
- **Iteration loop** — Claude picks up open issues, writes code, commits, and pushes
- **Built-in verification** — runs your test and lint commands after each iteration
- **Real-time streaming** — watch Claude's output live in the browser
- **Git diff viewer** — see exactly what changed in each iteration
- **User intervention** — pause, resume, inject guidance, or answer questions anytime
- **CLAUDE.md knowledge base** — persistent memory across iterations (architecture decisions, conventions, known issues)
- **GitHub integration** — issues, labels, commits, and pushes managed automatically
- **Project templates** — pre-configured setups for React, Next.js, Python, and static sites
- **Model selection** — choose between Claude Opus, Sonnet, or Haiku per project
- **Log export** — download full iteration history as JSON

## Prerequisites

- **Node.js 20+**
- **Claude Code CLI** — install and authenticate:
  ```bash
  npm install -g @anthropic-ai/claude-code
  claude login
  ```
- **GitHub CLI** — install and authenticate:
  ```bash
  # macOS
  brew install gh
  # or see https://cli.github.com/

  gh auth login
  ```

## Quick Start

```bash
# Clone this repo
git clone https://github.com/RobinWeitzel/claude-harness.git
cd claude-harness

# Install dependencies
npm install

# Start the harness
npm run dev:custom

# Open in browser
open http://localhost:3000
```

That's it. The harness runs on `http://localhost:3000`.

## Usage

### 1. Create a Project

Click **New Project** and fill in:
- **Project name** — display label
- **GitHub repo URL** — must be a repo you have push access to
- **Initial prompt** — describe what you want built
- **Template** (optional) — pre-fills test/lint commands for common stacks
- **Model** (optional) — choose which Claude model to use

### 2. Kick-off

Claude asks up to 10 clarifying questions to understand your requirements. Answer them or click **Skip to planning** when ready.

### 3. Planning

Claude creates GitHub Issues in your repo — one per task, with labels and priority ordering. Review them and click **Approve & Start**.

### 4. Autonomous Loop

Claude works through the issues automatically:
1. Reads the current state (`CLAUDE.md`, `STATUS.md`, open issues)
2. Picks the highest-priority open issue
3. Implements the changes
4. Runs tests and linting (if configured)
5. Commits and pushes
6. Closes the issue
7. Repeats until all issues are done

### 5. Monitor & Intervene

- **Live View** — real-time output streaming, iteration timeline, git diffs
- **Pause/Resume** — stop the loop and restart it anytime
- **Inject Guidance** — add instructions that Claude receives in the next iteration
- **Questions** — Claude can ask you questions; you answer in the WebUI

## How Context Passes Between Iterations

Each Claude session is stateless (subprocess). Context passes through three layers:

| Layer | Mechanism | Prompt Cost |
|-------|-----------|-------------|
| **Knowledge** | `CLAUDE.md` in workspace root | 0 (auto-read by CLI) |
| **Immediate state** | `.harness/STATUS.md` | ~200-500 tokens |
| **Task queue** | GitHub Issues (open/closed) | ~200-500 tokens |

Claude maintains `CLAUDE.md` with architecture decisions, conventions, key files, and known issues. The CLI auto-reads it — no prompt bloat.

## Configuration

### Settings Page (`/settings`)

- **Default test command** — e.g., `npm test`, `pytest`
- **Default lint command** — e.g., `npm run lint`, `ruff check .`
- **Iteration timeout** — max seconds per iteration (default: 1800 = 30 min)
- **Max iterations** — auto-pause after this many iterations (default: 100)

### Per-Project Settings

Set during project creation:
- Test/lint commands (override defaults)
- Branch name (default: `harness/main`)
- Claude model (default: your CLI's default model)

## Project Structure

```
src/
  app/                    # Next.js pages and API routes
    api/                  # REST API
    components/           # Shared UI components
    lib/                  # Shared utilities
    projects/             # Project pages (live view, kickoff, questions)
    settings/             # Settings page
    history/              # Project history
  lib/
    db/                   # SQLite schema and connection
    orchestrator/         # Core engine
      index.ts            # Main orchestration loop
      iteration-runner.ts # Runs a single iteration
      prompt-builder.ts   # Builds the prompt for each iteration
      output-parser.ts    # Parses Claude's output
      kickoff.ts          # Q&A and planning phases
      events.ts           # SSE event system
    project-manager.ts    # Project CRUD
    settings.ts           # Settings store
server.ts                 # Custom server entry point
```

## Auto-Completion

The harness automatically detects when all GitHub Issues are closed and marks the project as completed. It also pauses after 3 consecutive failed iterations or when the max iteration limit is reached.

## Development

```bash
# Run in development mode (with hot reload)
npm run dev:custom

# Run tests
npm test

# Build for production
npm run build

# Run production build
npm run start:custom
```

## License

MIT