Skip to content
Itervox

Getting Started

Install

Section titled “Install”

Itervox is a single Go binary. Install it with Homebrew:

Terminal window
brew tap vnovick/tap && brew install itervox

Or download the latest release from GitHub Releases.

Prerequisites

Section titled “Prerequisites”
  • An AI agent CLI — one of:
  • A project tracker — Linear or GitHub Issues

Quick Setup

Section titled “Quick Setup”

1. Initialize WORKFLOW.md

Section titled “1. Initialize WORKFLOW.md”

Navigate to your project repo and run:

Terminal window
itervox init --tracker linear --runner claude

This scans your repository, detects the tech stack, and generates a schema 2 WORKFLOW.md starter plus .itervox/agents/implementer, .itervox/agents/reviewer, and .itervox/agents/input-responder profile files.

For GitHub Issues:

Terminal window
itervox init --tracker github --runner claude

2. Configure secrets

Section titled “2. Configure secrets”

Create a .itervox/.env file (gitignored) with your API keys:

Terminal window
# For Linear
LINEAR_API_KEY=lin_api_xxxxx


# For GitHub (use a personal access token with repo scope)
GITHUB_TOKEN=ghp_xxxxx

Reference them in WORKFLOW.md as $LINEAR_API_KEY or $GITHUB_TOKEN.

Commit .itervox/agents/**; those files define your project agent profiles. Do not commit .itervox/.env, .itervox/HEARTBEAT.md, logs, or runtime queue files.

3. Run

Section titled “3. Run”
Terminal window
itervox

Itervox starts polling your tracker, spawning agents for active issues, streaming logs to the terminal, and writing .itervox/HEARTBEAT.md with current daemon state. By default it loads WORKFLOW.md from the current directory; pass -workflow <path> only if it lives elsewhere.

Open the dashboard at http://localhost:8090 to see the Kanban board.

4. (Optional) Verbose mode

Section titled “4. (Optional) Verbose mode”
Terminal window
itervox -verbose

Enables DEBUG-level logging including agent output.

What happens next

Section titled “What happens next”
  1. Itervox polls your tracker for issues in active states (default: “Todo”, “In Progress”)
  2. For each issue, it creates an isolated workspace (clone or worktree)
  3. An AI agent is spawned with your WORKFLOW.md prompt template plus the selected profile’s SOUL.md and INSTRUCTIONS.md
  4. The agent works on the issue, creates a branch, and submits a PR
  5. If the agent needs a human decision, Itervox pauses the issue in input_required and lets you reply from the dashboard or tracker
  6. Otherwise Itervox transitions the issue state on success

All of this is visible in real time via the web dashboard or terminal UI.

The spec behind Itervox

Section titled “The spec behind Itervox”

Itervox is the reference implementation of the Orchestrated Coding spec — a vendor-neutral system spec for running fleets of coding agents reliably (one orchestrator owning dispatch, isolated worktrees, durable handoffs, deterministic merge gates). Itervox conforms at L3, the spec’s highest level, with evidence-linked verification. See The Orchestrated Coding Spec for the full mapping and the conformance story.

Next steps

Section titled “Next steps”