Red Queen

Named for the AI that ran The Hive. Yours runs your SDLC.

Red Queen is to Claude Code what Jenkins is to bash.

A deterministic state machine that shuttles Jira or GitHub tickets through a configurable AI coding pipeline — spec, code, review, test, human review — and drops a merged PR out the end. The orchestrator itself spends zero AI tokens; it just dispatches Claude Code workers between phases and stops at the gates you configure.

TL;DR

You assign a ticket. Claude writes a spec. You approve at the human gate. Claude writes the code and opens a PR. Another Claude reviews it. Another tests it. You review the final PR and merge. Step in at any gate, or remove them entirely.

Phases, skills, and gates are all declared in redqueen.yaml — add a security-review phase, override a skill prompt by dropping a file into .redqueen/skills/. The graph is yours to shape.

Install

npm install -g redqueen

Requirements:

• Node.js >= 24
• An AI CLI installed and authenticated — Claude Code (claude --version must work in your shell; the default) and/or OpenAI Codex (codex --version, if you set agent: codex)
• An issue tracker: Jira Cloud or GitHub Issues
• A git repo with a remote on GitHub

Quickstart (Jira)

This is the primary path — Red Queen was built for teams already running Jira-driven SDLC.

1. Scaffold

In the root of your git repo:

redqueen init

Answer the prompts. Pick jira for issue tracker and github for source control. init writes redqueen.yaml, a gitignored .env, a codebase map, and reference templates under .redqueen/references/.

2. Fill in secrets

Open .env and set:

JIRA_TOKEN=...      # Atlassian API token (id.atlassian.com → Security)
GITHUB_PAT=...      # fine-grained PAT scoped to your repo

3. Discover Jira schema

Custom field IDs and phase option IDs are tenant-specific. Let Red Queen fetch them:

redqueen jira discover

This queries your Jira project, picks the phase and spec custom fields, matches each Red Queen phase against Jira option values, and patches redqueen.yaml with the resolved IDs. Unmatched phases stay as <CHANGE ME> — fix them manually. Use --dry-run to preview, --yes to skip the confirmation prompt.

4. Install the service

redqueen service install
redqueen service start

On macOS this generates a LaunchAgent under ~/Library/LaunchAgents/; on Linux, a --user systemd unit under ~/.config/systemd/user/. The installer auto-detects claude on your PATH and writes the absolute path into pipeline.claudeBin so the service's restricted PATH can't strand it.

5. Dashboard

Open http://127.0.0.1:4400. Five tabs:

• Status — live phase, queue depth, last poll, SSE event stream.
• Service — start / stop / restart the daemon, log paths.
• Config — edit redqueen.yaml in-browser; save triggers a hot reload and shows which sections applied vs. require restart.
• Skills — list bundled and user-overridden prompts; disable any skill via skills.disabled.
• Workflow — add, remove, reorder phases with live validation; refuses to save while tasks are in flight.

6. Assign a ticket

In Jira, set the AI Phase field on a ticket to Spec Writing and assign it to the AI bot account. The orchestrator polls every 30 seconds (or reacts to a webhook if configured). You'll see it move: Spec Writing → Spec Review (human gate) → Coding → Code Review → Testing → Human Review → merged.

A few things worth knowing about how the loop behaves:

• Spec rework loops back through Spec Feedback up to three times before escalating to a blocked gate.
• Code rework — whether from a failed Code Review or Testing — routes back to Coding and pushes to the same PR. The coder reads the prior phase from its context and either addresses reviewer blockers or reproduces the test failure locally before pushing.
• Code Review and Testing both comment on the PR every run. Review verdicts and an append-only test history land on the PR so you can see what each iteration produced without digging through logs.
• Skip the spec gate when the spec is ready. Set pipeline.skipSpecReviewIfReady: true and the orchestrator will jump straight from Spec Writing to Coding whenever the spec writer finishes with zero open questions. Leave it off (default) to always human-review the spec.

Alternative: GitHub Issues

If you'd rather drive the pipeline from GitHub Issues, pick github-issues at redqueen init. Labels (rq:phase:spec-writing, etc.) take the place of Jira custom fields. See the GitHub Issues adapter README for the full label convention and webhook setup.

Service management

redqueen service install     # write plist/unit + wrapper, enable, start
redqueen service status      # show install/run state + log paths
redqueen service start       # start (bootstrap if unloaded)
redqueen service stop        # stop + fully unload
redqueen service restart     # stop + start
redqueen service uninstall   # stop, disable, remove plist/unit

The wrapper script (.redqueen/run-redqueen.sh) sources .env before execing node redqueen start, so your plist/unit never contains secret values. Log paths default to .redqueen/redqueen.{out,err}.log under the project directory.

Configuration

All runtime config lives in redqueen.yaml. redqueen init writes a sensible default; the schema is documented inline in src/core/config.ts, and two full reference configs live under examples/ — one GitHub Issues, one Jira.

${ENV_VAR} references in the YAML are interpolated at load time from process.env (and from the adjacent .env file). Use ${JIRA_TOKEN} and ${GITHUB_PAT} for secrets — never paste literal values, the dashboard validator will reject them.

Choosing the worker agent

Workers run on Claude Code by default. pipeline.agent switches the default CLI, and any phase can override agent / model / effort individually — e.g. Claude for planning and review, Codex for coding:

pipeline:
  agent: claude-code # or codex; default claude-code
  model: opus        # optional; names are agent-specific — omit under codex
                     # to let ~/.codex/config.toml decide
  effort: high       # minimal|low|medium|high|xhigh|max — clamped to what the
                     # CLI supports (codex max→xhigh, claude minimal→low)

phases:
  - name: coding
    # ...routing fields...
    agent: codex     # per-phase override; wins over pipeline.agent
    model: gpt-5.3-codex
    effort: xhigh

Resolution is phase-over-pipeline per field, with one guard: the pipeline model never carries across an agent switch (model names are agent-specific). A phase that overrides only agent runs that CLI's default model. Codex runs report token usage but no dollar cost — add a pipeline.cost.pricing entry keyed by the model name to price them.

Stacked branches

Issues linked as blockers (Jira "blocks" links, GitHub issue dependencies) build on their blockers' branches: the dependent's worktree merges ancestor branches in topo order, and its PR targets the nearest still-gated ancestor branch so nothing merges past human review. When a blocker's PR merges, dependent PRs are retargeted onto the merged base and the merged code is folded into their branches.

Retargeting runs from the PR-merged webhook. If you run poll-only (pipeline.webhooks.enabled: false), turn on GitHub's "Automatically delete head branches" so GitHub retargets dependent PRs itself when the merged branch is deleted — with neither, a dependent PR keeps targeting the stale merged branch (PR bases are only computed at creation).

Verification checklist

After redqueen service start:

• redqueen status prints Red Queen — running with a PID.
• The dashboard at http://127.0.0.1:4400 loads and the Service tab shows the state pill as running.
• An assigned ticket moves from the entry phase into the first automated phase within one poll interval.
• .redqueen/audit.log shows phase transitions as they happen.
• redqueen service stop followed by redqueen service start leaves the service running.

Troubleshooting

Symptom	Likely cause	Fix
command not found: redqueen	Global install failed or not on PATH	Re-run npm install -g redqueen, verify which redqueen
Service starts but workers fail with claude: command not found	claude not on the service's runtime PATH	Re-run redqueen service install to re-detect, or set pipeline.claudeBin explicitly
Workers fail with codex binary not found	codex not on the (service's) runtime PATH	Set pipeline.codexBin to the absolute path (which codex) — service install only auto-detects claude
Clicking Dashboard Stop leaves no way to restart from the UI	Expected — the dashboard is served by the service it just killed	Run redqueen service start from a terminal
Jira issues aren't being picked up	Webhook not delivering or customFields wrong	Check .redqueen/audit.log, run redqueen jira discover --dry-run, confirm the Jira webhook is reaching your publicBaseUrl
401 Unauthorized from GitHub	PAT missing a scope	Regenerate fine-grained PAT with Contents / Issues / PRs / Workflows / Metadata
Worker stalls mid-phase	Claude Code prompt hit an unexpected state	Check .redqueen/audit.log; phase retries up to 3, then escalates to blocked

Per-adapter troubleshooting lives in each adapter's README.

Architecture

flowchart LR
  subgraph cli["CLI (src/cli/)"]
    init[init]
    service[service]
    jira[jira discover]
    helpers["issue / spec / pr / pipeline helpers"]
  end

  subgraph core["Core runtime (src/core/)"]
    orchestrator[Orchestrator]
    queue[SQLite task queue]
    stateStore[Pipeline & orchestrator state]
    audit[Audit logger]
    worker[Worker manager]
  end

  subgraph integrations["Integrations (src/integrations/)"]
    jiraAdapter[Jira adapter]
    ghIssues[GitHub Issues adapter]
    ghSC[GitHub source control]
  end

  subgraph edges["HTTP surfaces"]
    dashboard[Dashboard / SSE]
    webhook[Webhook server]
  end

  subgraph ext["External"]
    claude[Claude Code CLI]
    jiraApi[Jira Cloud]
    ghApi[GitHub API]
  end

  orchestrator --> queue
  orchestrator --> stateStore
  orchestrator --> audit
  orchestrator --> worker
  orchestrator --> jiraAdapter
  orchestrator --> ghIssues
  orchestrator --> ghSC
  worker --> claude
  jiraAdapter --> jiraApi
  ghIssues --> ghApi
  ghSC --> ghApi
  dashboard --> stateStore
  webhook --> orchestrator
  helpers --> jiraAdapter
  helpers --> ghIssues
  helpers --> ghSC

Loading

Adapter pattern — all issue trackers implement IssueTracker, all source control implements SourceControl. Adding Linear or Bitbucket is a new adapter, not a core change.

For AI agents

Working inside this repo? Start with AGENTS.md — build commands, code style, interfaces. Installing Red Queen into a user's project? Hand this to your agent:

"Install redqueen, run redqueen init for jira + github, fill the tokens in .env, then redqueen jira discover, then redqueen service install && redqueen service start."

LLM crawler index: llms.txt.

Links

• CHANGELOG.md — release notes
• CONTRIBUTING.md — dev loop, code style, adding adapters
• LICENSE — MIT
• Examples — copy-pasteable reference configs
• Website
• Issue tracker