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, or none: the local tracker keeps issues as Markdown files in your repository

Try it first: itervox demo

Section titled “Try it first: itervox demo”
Terminal window
itervox demo

Opens a throwaway board with fake issues and a scripted agent: no tracker account, API keys or agent CLI needed, and nothing is written outside a temporary directory. Within about a minute you see issues run, ask for input, fail and retry, go to review and finish. See itervox demo.

Quickstart: one command

Section titled “Quickstart: one command”

In your project repository:

Terminal window
itervox quickstart

It takes you from a repository to a running board:

  1. Detects the tracker and the agent CLI. LINEAR_API_KEY set → Linear; otherwise an origin remote on github.com → GitHub Issues; otherwise the local tracker. The agent is claude if it is on your PATH, otherwise codex. Override either with --tracker github|linear|local and --runner claude|codex.
  2. Writes WORKFLOW.md (schema 2) and the .itervox/agents/ profiles, the same files itervox init writes. An existing schema-2 workflow is used as it is; an older one is migrated with itervox init --update only after you confirm.
  3. Sets up the tracker token. For GitHub without GITHUB_TOKEN, it offers your gh CLI’s token (gh auth token) and saves it to the gitignored .itervox/.env if you agree. For Linear, put LINEAR_API_KEY in .itervox/.env first.
  4. Creates missing GitHub state labels after asking (the same step as itervox doctor --fix).
  5. Runs itervox doctor and stops with its report if anything is wrong.
  6. Starts the daemon in the background, waits for /api/v1/ready, and prints the dashboard URL and the file that holds the API token. The daemon’s output goes to .itervox/logs/quickstart-daemon.log; stop it with itervox stop.

Re-running is safe: nothing is overwritten without asking, and if the daemon is already running quickstart prints its URL instead of starting another. Pass --yes to accept every prompt (for scripts) or --no-start to stop after the checks.

The steps below do the same by hand.

Manual setup

Section titled “Manual 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

GitHub tracks states as labels, so create them before the first run (itervox doctor --fix does it for you), and authenticate the gh CLI. The GitHub Issues guide covers labels, p0–p3 priority labels, blocker phrases, #42 identifiers and gh auth.

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 to see the Kanban board. If you omitted server.port from WORKFLOW.md, it defaults to http://localhost:8090 — but itervox init scaffolds server.port: 0 (OS-assigned), so don’t assume 8090 blindly. Find the actual URL in .itervox/dashboard_url or the dashboard URL: line of itervox doctor — both give the token-free URL (no bearer token is stored there). The dashboard also needs the bearer token, which comes from one of: the TUI’s w key (copies the tokenised URL to the clipboard), the tokenised URL printed once on the startup terminal’s stderr (only when stderr is a terminal), <logs-dir>/api-token for an auto-generated token (mode 0600; <logs-dir> defaults to ~/.itervox/logs/<kind>/<slug>-<project>/), or the value you pinned as ITERVOX_API_TOKEN in .itervox/.env. See Remote access → The API token.

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”