npm package: @ob1-sg/horizon
Description: Turn Linear Tickets into Pull Requests with Parallel Agents
Author: OB1
Latest version: 0.2.2

# Horizon - Turn Linear Tickets into Pull Requests with Parallel Agents

Horizon turns Linear tickets into pull requests with code changes. You write tickets, Horizon runs a loop of researching, planning, implementing, and validating changes on its own. Multiple Horizon agents can work in parallel so you can focus on reviewing high-quality PRs. The validation pipeline ensures the pull requests are tested, easy to review, and ready to merge.

## Prerequisites

- Node v24.12.0 (only version tested so far)
- [Claude Code (recommended)](https://code.claude.com/docs/en/setup#installation) or OpenAI Codex CLI installed
- A Linear account with API access
- Git repository initialized

## Installation

### Global Installation (Recommended)

```bash
npm install -g @ob1-sg/horizon
```

### Local Project Installation

```bash
npm install --save-dev @ob1-sg/horizon
```

## Quick Start

1. **Install Horizon** (see above)

2. **Run Horizon** in your project:
   ```bash
   cd your-project-with-git-initialized
   horizon              # Global install
   npx horizon          # Local install
   ```

3. **First-run wizard** — Horizon walks you through setup:
   - Enter your Linear API key
   - Auto-detects your Linear team (or lets you pick)
   - Auto-selects AI provider (Claude Code or OpenAI Codex) based on what's installed, defaulting to Claude Code
   - Choose merge mode: `auto` (recommended), `merge`, or `pr`
   - Creates `.horizon/` config directory
   - Sets up Horizon Agent's `∞` workflow statuses in your Linear team

4. **Create tickets** in Linear and Horizon works on them autonomously

Run `horizon config` to change settings like provider, model, and iteration limits.

## How It Works

### The Agent Pipeline

1. **Agent 1 (Linear Reader)**: Scans Linear for available tickets, prioritizes by urgency, **claims** the highest-priority ticket, and gathers context.

2. **Agent 2 (Worker)**: The developer. Reads code, writes code, runs tests, and commits changes.

3. **Agent 3 (Linear Writer)**: Updates Linear with results - posts comments, updates status, and links commits.


### The Agent Loop

```
+-----------------------------------------------------------------------+
|                        Instance (yellow-giraffe)                      |
+-----------------------------------------------------------------------+
|                                                                       |
|  Loop 1: Ticket PROJ-12                                               |
|  +------------+     +------------+     +------------+                 |
|  |  Agent 1   |     |  Agent 2   |     |  Agent 3   |                 |
|  |  Linear    |---->|  Worker    |---->|  Linear    |                 |
|  |  Reader    |     |            |     |  Writer    |                 |
|  +------------+     +------------+     +------------+                 |
|                                                                       |
|  Loop 2: Ticket PROJ-13                                               |
|  +------------+     +------------+     +------------+                 |
|  |  Agent 1   |---->|  Agent 2   |---->|  Agent 3   |                 |
|  +------------+     +------------+     +------------+                 |
|                                                                       |
|  Loop 3: ...                                                          |
|                                                                       |
+-----------------------------------------------------------------------+
```

1. Create a ticket in Linear and set its status to `Backlog (default)` (or any `Needs ...` status)
2. Horizon claims it, does the work, and advances to the next stage
3. This repeats automatically until the ticket reaches `∞ Done`
4. Retry any stage by moving the ticket back to `Backlog` (or any `Needs ...` status)
5. Queue multiple tickets — Horizon processes them by priority, which you can configure in Linear. Provide feedback or unblock the agent when human intervention is needed

### Parallel Execution

Run `horizon` in a separate terminal window for each parallel agent. Agents coordinate through Linear: when one agent claims a ticket, it changes the status to "In Progress" so other agents skip it. Agent 1 (the orchestrator) understands ticket hierarchy and dependencies, so it picks the right work in the right order. Each instance runs loops continuously until there's no more work.

### Git Worktree Isolation

Each Agent 2 (Worker) runs in its own [git worktree](https://git-scm.com/docs/git-worktree), so multiple agents can work on different tickets in parallel without conflicts. When a ticket is claimed:

1. Horizon creates a worktree at `.horizon/worktrees/{issue-identifier}/`
2. The worktree checks out a dedicated branch: `horizon/{issue-identifier}`
3. Dependencies are installed in the worktree automatically
4. Agent 2 runs entirely within the worktree
5. After completion, the worktree is cleaned up

This means you can run multiple `horizon` instances simultaneously — each one gets an isolated copy of the repo with its own branch, so there are no working directory conflicts between agents.

## Directory Structure

After running Horizon, your project will have:

```
your-project/
├── .horizon/              # Runtime data (gitignored)
│   ├── env                # Configuration and credentials
│   ├── mcp.json           # MCP configuration for Claude Code
│   ├── prompts/           # Agent prompt templates (synced from package)
│   ├── output/            # Runtime logs
│   ├── worktrees/         # Git worktrees for parallel agents
│   └── attachments/       # Downloaded issue attachments
├── horizon-docs/          # Work artifacts (committed)
│   ├── research/          # Research documents
│   ├── plans/             # Implementation plans
│   ├── validation/        # Validation reports
│   ├── oneshot/           # Oneshot completions
│   ├── specifications/    # Feature specifications
└── CLAUDE.md              # Your project's Claude instructions
```

### Horizon Documentation Folder

The `horizon-docs/` folder contains the work artifacts for Horizon. You can use this folder to track the work that Horizon has done.

However, the main purpose of this folder is for the agent to document its work and historical changes, which are valuable for understanding the codebase evolution and development of future features.

## Configuration

### Environment Variables

Set these in `.horizon/env` or export them:

| Variable | Description | Default |
|----------|-------------|---------|
| `LINEAR_API_KEY` | Your Linear API key | (required) |
| `LINEAR_TEAM_KEY` | Linear team identifier (e.g., "RSK") | (required) |
| `HORIZON_PROVIDER` | AI provider: "claude" or "codex" | "claude" |
| `HORIZON_CLAUDE_MODEL` | Claude model: "opus", "sonnet", "haiku" | "opus" |
| `HORIZON_MAX_ITERATIONS` | Stop after N iterations (0 = unlimited) | 0 |
| `HORIZON_MERGE_MODE` | Merge mode: "auto", "merge", or "pr" | "auto" |

### Merge Modes

Horizon supports three modes for completing work:

**Auto (default)**
```bash
export HORIZON_MERGE_MODE=auto
```
The agent decides the safest path — merge directly for small changes, create a PR for larger ones.

**Direct Merge**
```bash
export HORIZON_MERGE_MODE=merge
```
Horizon merges completed work directly to main. Best for trusted autonomous operation.

**Pull Request**
```bash
export HORIZON_MERGE_MODE=pr
```
Horizon creates a pull request instead of merging. The ticket moves to `∞ Awaiting Merge` status until a human reviews and merges the PR. Best for teams that want human oversight.

### Using Codex CLI as Provider

When using Codex (`HORIZON_PROVIDER=codex`), configure Linear MCP in Codex:

```bash
codex mcp add linear --url https://mcp.linear.app/mcp
```

## CLI Commands

```bash
horizon              # Run the main development loop
horizon config       # Configure Horizon settings
horizon uninstall    # Remove Horizon from current project
horizon --help       # Show help
horizon --version    # Show version
```

## Updates

Horizon automatically checks for updates once per day. When a new version is available, you'll see a notification on startup:

```
   Update available: 0.1.3 → 0.1.4
   Run: npm install -g @ob1-sg/horizon@latest
```

Update with:

```bash
npm install -g @ob1-sg/horizon@latest
```

## Writing Good Tickets

Horizon works best with clear, specific tickets:

**Good ticket**:
> Add a dark mode toggle to the settings page. Should save preference to localStorage and apply a .dark-theme class to the body.

**Tips**:
- Include **acceptance criteria** when possible
- Reference existing code patterns to follow
- Specify any constraints or requirements
- Link related issues if dependencies exist

## Linear Workflow Statuses

Horizon creates these statuses in Linear:

**Backlog**:
- `Backlog (default)`

**Ready statuses** (waiting for Horizon):
- `∞ Needs Research`
- `∞ Needs Specification` (optional - when UX decisions are needed)
- `∞ Needs Plan`
- `∞ Needs Implement`
- `∞ Needs Validate`

**In Progress statuses** (Horizon is working):
- `∞ Research In Progress`
- `∞ Specification In Progress`
- `∞ Plan In Progress`
- `∞ Implement In Progress`
- `∞ Validate In Progress`
- `∞ Oneshot In Progress`

**Intervention statuses** (requires human action):
- `∞ Blocked` - Agent needs clarification or decision before proceeding
- `∞ Awaiting Merge` - Work complete, PR awaiting human review/merge (PR mode only)

**Terminal statuses**:
- `∞ Done`
- `∞ Canceled`

## Developing Horizon

If you want to contribute or modify Horizon:

See [CONTRIBUTING.md](CONTRIBUTING.md) for release process and maintainer guidelines.

## Acknowledgments

Horizon builds on ideas and techniques from the AI engineering community:

- **[Ramp Inspect](https://builders.ramp.com/post/why-we-built-our-background-agent)** - For agent UIUX, infrastructure and tooling inspiration.
- **[Stripe Minions](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents)** - For the architecture and design of multiple agents working in parallel.
- **[Dex Horthy](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md)** - For the research/plan/implement pattern that structures how Horizon approaches work
- **[Geoff Huntley](https://ghuntley.com/ralph/)** - For the Ralph Wiggum technique that inspires Horizon's autonomous agent approach
- **[Vaibhav's BoundaryML Podcast](https://boundaryml.com/podcast)** - For "AI That Works" podcast series on building reliable AI systems

## License

MIT