@ob1-sg/horizon

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) or OpenAI Codex CLI installed
• A Linear account with API access
• Git repository initialized

Installation

Global Installation (Recommended)

npm install -g @ob1-sg/horizon

Local Project Installation

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

Quick Start

• Install Horizon (see above)

• Run Horizon in your project:

  cd your-project-with-git-initialized
  horizon              # Global install
  npx horizon          # Local install
  

• 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

• 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

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

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

• 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: ...                                                          |
|                                                                       |
+-----------------------------------------------------------------------+

• Create a ticket in Linear and set its status to Backlog (default) (or any Needs ... status)
• Horizon claims it, does the work, and advances to the next stage
• This repeats automatically until the ticket reaches ∞ Done
• Retry any stage by moving the ticket back to Backlog (or any Needs ... status)
• 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, so multiple agents can work on different tickets in parallel without conflicts. When a ticket is claimed:

• Horizon creates a worktree at .horizon/worktrees/{issue-identifier}/
• The worktree checks out a dedicated branch: horizon/{issue-identifier}
• Dependencies are installed in the worktree automatically
• Agent 2 runs entirely within the worktree
• 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)

export HORIZON_MERGE_MODE=auto

The agent decides the safest path — merge directly for small changes, create a PR for larger ones.

Direct Merge

export HORIZON_MERGE_MODE=merge

Horizon merges completed work directly to main. Best for trusted autonomous operation.

Pull Request

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:

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

CLI Commands

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:

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 for release process and maintainer guidelines.

Acknowledgments

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

• Ramp Inspect - For agent UIUX, infrastructure and tooling inspiration.
• Stripe Minions - For the architecture and design of multiple agents working in parallel.
• Dex Horthy - For the research/plan/implement pattern that structures how Horizon approaches work
• Geoff Huntley - For the Ralph Wiggum technique that inspires Horizon's autonomous agent approach
• Vaibhav's BoundaryML Podcast - For "AI That Works" podcast series on building reliable AI systems

License

MIT