agent-valley

# Agent Valley

Linear webhook-driven agent orchestration platform. Register an issue on Linear, and AI agents (Gemini, Codex, Gemini) automatically develop it in isolated git worktrees — in parallel.

> Read this in: [한국어](./README.ko.md)

```
Linear Issue (Todo)
  → Webhook → Orchestrator → Git Worktree → Agent Session
  → Completion → Merge/PR → Done
```

**Key principle:** Agent Valley is a scheduler/runner. It manages lifecycle state transitions (Todo → In Progress → Done/Cancelled) and posts work summaries. Agents focus on business logic (code writing, PR creation).

Built with **TypeScript + Bun**. Supports **Claude Code, Codex, and Gemini CLI** out of the box via the AgentSession plugin system — add custom agents by implementing a single interface.

---

## How It Works

1. Create an issue on Linear (or `bun av issue "description"`)
2. Linear sends a webhook to the dashboard
3. Orchestrator verifies HMAC signature, transitions the issue to In Progress
4. DAG scheduler checks dependencies — blocked issues wait until blockers complete
5. WorkspaceManager creates an isolated git worktree in `WORKSPACE_ROOT`
6. AgentRunnerService spawns the agent (Gemini / Codex / Gemini)
7. On completion: auto-merge to main (or create PR), post summary to Linear, transition to Done
8. On failure: exponential backoff retry (60s × 2^n, max 3 attempts), then cancel with error comment
9. Slot refill: completed agents free up capacity, next waiting issue starts automatically

Multiple issues run in parallel up to `MAX_PARALLEL` (auto-detected from hardware).

---

## Quick Start

```bash
# Clone
git clone https://github.com/first-fluke/agent-valley.git
cd agent-valley
bun install

# Interactive setup wizard
bun av setup

# Or copy template and fill in manually
cp valley.example.yaml valley.yaml

# Start (dashboard + orchestrator + ngrok tunnel)
bun av dev
```

Copy the ngrok URL printed to the console into Linear webhook settings → `{url}/api/webhook`.

---

## CLI

```bash
bun av s