Igniter

A software factory for coding agents.

Turn Linear tickets into working features with independent acceptance testing and delivery you approve. A Commander runs in your terminal and coordinates Build, Acceptance, and Deliver agents through Herdr.

• Isolated work. Each ticket gets a Git worktree and a team of agents.
• Independent acceptance. A separate agent tests the public UI, CLI, or API against your criteria without seeing the source, diff, or Build plan.
• Your choice of agents. Configure named Codex, Claude Code, or OpenCode profiles for the Commander to choose from.
• Approval before delivery. Review the evidence and decide when a change lands.

The workflow

You approve the first Build and authorize delivery after Acceptance passes. Delivery follows your repository's instructions. When Acceptance finds issues, Build fixes them and returns directly to Acceptance. Deployment requires your authorization.

Linear holds ticket state; Herdr hosts the agents. Igniter connects them directly, with no background service.

Dependencies

• Bun 1.3.11+ — runs Igniter; must be on PATH.
• Git — isolates ticket work in worktrees.
• Herdr — installed and running; hosts worker agents.
• Agent CLI — install and authenticate the CLIs selected for your roles. The defaults use Codex; you can configure Claude Code or OpenCode instead.
• Linear — a project and a LINEAR_API_KEY environment variable.

Get started

Install

bun add --global @minipai/igniter

Connect a project

From your Git repository root, run:

igniter start

If the project is not configured, confirm the initialization prompt. For manual setup, create .igniter/config.yaml in the repository root:

project: Your Linear project
team: ENG
linear_org: your-workspace-slug
max_running: 3

project accepts a project name or slug; team accepts a team name or key. Use your Linear workspace slug for linear_org.

Prepare these statuses on the project's Linear team:

Status	Linear status type
Backlog	Backlog
Todo	Unstarted
Build, Acceptance, Deliver	Started
Done	Completed
Canceled	Canceled

Create these child labels under a Progress label group:

Label group	Child label
Progress	Pending
Progress	In progress
Progress	Complete
Progress	Blocked

Use the status and label names exactly as shown; Igniter validates them when a command runs.

Give each ticket observable acceptance criteria, for example:

## Acceptance criteria

- [ ] Exporting the filtered table produces a CSV containing only visible rows.
- [ ] An empty result produces a CSV with headers and no data rows.

Start

From the project root, with LINEAR_API_KEY set:

igniter start

This opens the Commander in your terminal. If it is already open from project setup, continue in that session.

Configure agents

Define profiles under agents in .igniter/config.yaml. Each profile is a complete shell command:

agents:
  builder:
    command: "opencode mini -m opencode-go/deepseekflash-4.1"
  builder_backup:
    command: "claude --model sonnet"
  specialist:
    command: "HERDR_AGENT=opencode opencode2 mini -m provider/model"
  commander:
    command: "opencode --prompt {prompt}"

The Commander command receives its prompt through the unquoted {prompt} placeholder. Worker commands must not include that placeholder. Same-named profiles replace the bundled command as a whole; if command is omitted, the entire bundled command is inherited. New profile names require a non-empty command, and profile settings other than command are rejected.

Commands include the executable name, model flags, and effort flags verbatim; Igniter does not translate CLI options. The Commander runs through sh -c, with {prompt} replaced by one shell-quoted argument. Workers run in their Herdr pane's shell and receive work through agent.prompt after detection. Use HERDR_AGENT=opencode when a renamed executable or wrapper needs Herdr's OpenCode detection rules. The command must stay in the foreground.

Replace the old harness, model, and effort settings with command. To change a running worker's command, use igniter worker restart ENG-123 --command 'opencode2 mini -m provider/model'. igniter worker answer ENG-123 enter sends that exact key; y and n are literal keys too, not portable approve/reject actions.

Worker retries retain their selected command. Full command records live in $XDG_STATE_HOME/igniter/worker-records (default ~/.local/state/igniter/worker-records); Herdr metadata holds short references so its token length limit cannot truncate commands.

commander configures the Commander. builder, acceptance, and deliverer are the defaults for their stages. Additional names, including the bundled builder_backup and builder_expert, are candidates the Commander can select with igniter worker start ENG-123 --agent specialist. There is no automatic fallback or priority implied by a profile's name.

Assign a ticket

Create a ticket in your configured Linear project with acceptance criteria, then move it to Todo. In the Commander conversation, ask it to start the ticket:

Start ENG-123.

Replace ENG-123 with your ticket ID. The Commander reads the ticket, prepares a worktree, and starts the Build agent. Review its evidence when it asks for your Build approval; after Acceptance passes, approve delivery according to your repository's instructions.

Documentation

• Workflow operations — reports, approvals, worker recovery, cancellation, and command migration.
• Project runbooks — add repository-specific instructions for Build, Acceptance, and Deliver.
• Agent defaults — command strings that projects can override under agents in .igniter/config.yaml.

Development

From a source checkout:

bun install
bun run check

Checks include typechecking, unit tests, and CLI end-to-end tests. Tests use isolated fixtures, without real credentials or provider calls.

License

MIT. See LICENSE.