Constellation ⭐

AI agent pipeline orchestrator — plan, debate, validate, develop, review, test.

Constellation drives a squad of specialized AI agents through a structured pipeline to turn task descriptions into tested, PR-ready code. Adapter-agnostic: works with Claude Code, Codex CLI, GitHub Copilot CLI, or any CLI coding agent.

Pipeline

[Optimize (Spica)] → Plan (Vega) → Debate (Antares) → Validate (Deneb) → Develop (Rigel) → Test (Polaris) → Review (Altair)

Agent	Role	When
Spica	Task optimizer — interactive Q&A to refine vague descriptions	Optional (`optimize`)
Vega	Planner — breaks features into subtasks with acceptance criteria	Always
Antares	Devil's advocate — challenges the plan, flags risks	High/critical priority
Deneb	Spec validator — finds ambiguities and misinterpretation traps (confidence scoring)	High/critical priority
Rigel	Developer — implements subtasks, sequentially or in parallel	Always
Polaris	Tester — runs tests, verifies acceptance criteria	Always
Altair	Reviewer — code review with APPROVE/REVISE verdicts	Always

The orchestrator (Procyon) coordinates them: handles retries, tracks state, manages branches/worktrees, and creates the PR when all agents pass.

How It Works

Spica (optional) refines vague task descriptions through interactive Q&A
Vega reads your codebase and produces a plan with acceptance criteria and subtasks
Antares challenges the plan (high-priority tasks only) — Vega replans if challenged, then Antares re-validates
Deneb validates the spec for ambiguities (high-priority tasks only) — confidence scoring (≤2: replan, 3: proceed with notes, 4-5: pass)
Rigel implements each subtask — in parallel if files don't overlap, sequentially otherwise
Polaris runs tests and verifies acceptance criteria — fix loop if needed
Altair reviews the code — if it finds issues, a fix Rigel is spawned, then re-reviewed
Pre-PR checks run (build/lint/test) — fix Rigel spawned if they fail
PR is created automatically, task moves to human-test

Requirements

Node.js ≥ 18
Git ≥ 2.20
At least one supported CLI coding agent:
- Claude Code CLI (claude)
- Codex CLI (codex)
- GitHub Copilot CLI (copilot)
tmux (optional, for resilient background runs)

Installation

# Clone and install
git clone https://github.com/AndurilCode/constellation.git
cd constellation && npm install

# Option 1: Shell wrapper (run from source)
./bin/constellation.sh run TASK-001

# Option 2: Global symlink
npm link
constellation run TASK-001

Quick Start

# Initialize in your project
cd your-repo
constellation init

# Create a task
constellation create --title "Add structured logger" \
  --desc "Replace console.log with a structured logger" \
  --priority high

# Run the full pipeline
constellation run TASK-001

# Optionally refine a vague description first
constellation optimize TASK-001   # Interactive Q&A with Spica

# Run the pipeline
constellation run TASK-001 --supervised  # With human checkpoints
constellation run TASK-001               # Or fully automated

# Monitor via live dashboard
constellation dashboard

# Or run in a resilient tmux session
constellation run TASK-001 --tmux
constellation peek TASK-001     # Check progress
constellation attach TASK-001   # Reattach

Commands

Dashboard

constellation dashboard              # Live Ink-powered dashboard
constellation dashboard --once       # Single render (no live updates)

The dashboard is the primary control surface:

Task list — grouped by Running/Todo/Done
Pipeline view — per-agent status, verdicts, durations, cost tracking
Agent detail — run navigation, scrollable report preview with markdown rendering
Agent logs — browse NDJSON stream logs per agent (◁▷ to switch)
Actions: [c] create, [o] optimize (Spica), [r] run, [s] stop, [e] edit, [d] delete (with full cleanup)
Stop resets task to todo with ⏸ pause icons on in-progress subtasks
Run resumes from the last phase (--from auto-detected)

Supervised Mode

constellation run TASK-001 --supervised       # Human checkpoints after Vega and Rigel

In supervised mode, the pipeline pauses at checkpoints and waits for human approval. From the dashboard:

[a] approve — continue to next phase
[c] challenge — provide feedback, agent re-runs with your input
[r] reject — stop the pipeline

Checkpoints are not skippable — no timeout, no force flag. Human is the gate.

Pipeline

constellation run TASK-001                    # Full pipeline (autopilot)
constellation run TASK-001 --supervised       # With human checkpoints
constellation run TASK-001 --from developing  # Resume from phase
constellation run TASK-001 --dry-run          # Preview without executing
constellation run TASK-001 --skip-planning    # Skip Vega, start at Rigel
constellation run TASK-001 --tmux             # Run in detached tmux session

Runtime overrides (CLI flags override constellation.json):

# Override adapter/model/effort for the whole run
constellation run TASK-001 --adapter copilot-cli --model claude-opus-4-6 --effort high

# Per-agent overrides (repeatable)
constellation run TASK-001 \
  --agent vega.adapter=copilot-cli \
  --agent vega.model=claude-sonnet-4.5 \
  --agent rigel.adapter=codex-cli \
  --agent rigel.model=gpt-5.3-codex

# Budget and timeout overrides
constellation run TASK-001 --budget 1 --timeout 300

Session Management (tmux)

constellation sessions                      # List active pipeline sessions
constellation attach TASK-001               # Reattach to running pipeline
constellation peek TASK-001 [--lines 50]    # Show recent output without attaching
constellation kill TASK-001                  # Kill a running pipeline

Board

constellation init                  # Interactive setup (auto-detects language/tools)
constellation init --ci             # Non-interactive (CI/scripts)
constellation status                # Board overview
constellation dashboard [--once]    # Live terminal dashboard
constellation list [--state <s>]    # List tasks (filter by state)
constellation show TASK-001         # Task details + subtasks + agent runs
constellation create --title "..."  # Create task
  [--desc "..."] [--priority high] [--deps TASK-001] [--project <key>]
  [--criteria "c1|c2"] [--files "f1,f2"] [--skip vega] [--fast]
constellation move TASK-001 <state> [--reason "..."] [--force]
constellation assign TASK-001 <agent>
constellation block TASK-001 --reason "..."
constellation files TASK-001 --add "path1,path2"
constellation conflicts [TASK-001]  # Check file overlaps between tasks
constellation stats TASK-001        # Agent run times, verdicts, costs
constellation models                # Show/set agent model overrides
constellation cleanup [--delete]    # Remove stale worktrees from /tmp

Subtasks

constellation subtask add TASK-001 --title "..." [--desc "..."] [--files "..."]
constellation subtask list TASK-001
constellation subtask show TASK-001-01
constellation subtask move TASK-001-01 <state> [--reason "..."]
constellation subtask assign TASK-001-01 <agent>
constellation subtask remove TASK-001-01

Pipeline Control (Advanced)

constellation dispatch TASK-001                          # Generate agent prompt
constellation pipeline TASK-001 altair APPROVE --exec    # Process verdict
constellation auto-process TASK-001 rigel --report-file report.md
constellation next-subtask TASK-001 [--parallel]         # Get next dispatch
constellation complete-subtask TASK-001-01 COMPLETE [--report-file r.md]
constellation worktrees TASK-001 [--create]              # Parallel worktree setup
constellation apply-plan TASK-001 [--file plan.md]       # Apply Vega plan manually
constellation report TASK-001 altair [--file r.md]       # Read/save agent reports
constellation extract-report session.jsonl [--verdict-only]
constellation check-done TASK-001-01                     # Heuristic completion check

Configuration

constellation.json in your project root:

{
  "adapter": "claude-cli",
  "agents": {
    "vega": {
      "model": "claude-sonnet-4-5",
      "effort": "high",
      "maxBudgetUsd": 2,
      "timeoutSeconds": 600
    },
    "rigel": {
      "adapter": "codex-cli",
      "model": "gpt-5.3-codex",
      "effort": "medium",
      "maxBudgetUsd": 3,
      "timeoutSeconds": 600
    },
    "altair": {
      "adapter": "copilot-cli",
      "model": "claude-sonnet-4.5",
      "effort": "medium",
      "maxBudgetUsd": 2,
      "allowedTools": ["Read", "Bash(grep:*)", "Bash(find:*)", "Bash(git:*)"]
    },
    "polaris": {
      "model": "claude-sonnet-4-5",
      "effort": "medium",
      "maxBudgetUsd": 2
    }
  }
}

Agent Config Fields

Field	Type	Description
`adapter`	`string`	Override global adapter for this agent
`model`	`string`	Model name (e.g. `claude-sonnet-4.5`, `gpt-5.3-codex`)
`effort`	`low\|medium\|high`	Reasoning effort level
`maxBudgetUsd`	`number`	Max dollar spend per agent run
`timeoutSeconds`	`number`	Kill agent if exceeded
`allowedTools`	`string[]`	Tool whitelist
`disallowedTools`	`string[]`	Tool blacklist
`outputFormat`	`text\|json\|stream-json`	Output format preference

Config Resolution Order

constellation.json defaults → agents.<name> → CLI flags (highest priority)

Adapters

Constellation uses a pluggable adapter system. Each adapter implements the AgentAdapter interface:

Adapter	CLI	Key Flags	Notes
claude-cli	`claude`	`--print`, `--system-prompt`, `--effort`	PTY wrapper (`script -qc`), auto-resolves latest binary
codex-cli	`codex`	`exec --full-auto`, `-m`, `-c`	No PTY needed, JSONL event parsing
copilot-cli	`copilot`	`-p`, `--yolo`, `--silent`, `--model`	No PTY needed, `--share` for transcripts

Mix adapters per agent:

{
  "adapter": "claude-cli",
  "agents": {
    "vega": { "adapter": "copilot-cli", "model": "claude-sonnet-4.5" },
    "rigel": { "adapter": "codex-cli", "model": "gpt-5.3-codex" }
  }
}

Writing a Custom Adapter

Implement the AgentAdapter interface in src/adapters/:

interface AgentAdapter {
  readonly name: string
  spawn(options: AgentSpawnOptions): Promise<AgentHandle>
  isAvailable(): Promise<boolean>
  version(): Promise<string>
}

Task States

todo → planned → debating → validating → developing → review → test → human-test → done
                                                                         ↕
                                                                      on-hold

Backward moves require --reason. State guards enforce prerequisites (e.g., can't enter review without a branch).

Key Features

Live Ink dashboard — 3-level navigation (task list → pipeline → agent detail), full task lifecycle from the terminal
Supervised mode — human checkpoints after Vega and Rigel; approve/challenge/reject from the dashboard
Spica task optimizer — interactive Q&A to turn vague descriptions into precise specs with acceptance criteria
Multi-adapter pipeline — mix Claude, Codex, and Copilot CLIs in the same run, per-agent
Parallel Rigel dispatch — subtasks with non-overlapping files run simultaneously in separate git worktrees, then merge back
Antares challenge loop — devil's advocate challenges plans; Vega replans then Antares re-validates (max 2 rounds)
Deneb confidence scoring — spec validation with routing: ≤2 triggers replan, 3 proceeds with warnings, 4-5 passes clean
Auto-fix loops — REVISE verdicts from Altair/Polaris spawn fix Rigels; pre-PR check failures too
Stop & resume — stop resets to todo with ⏸ paused subtasks; run auto-detects --from phase
Agent learnings — agents report lessons in verdict JSON; stored and injected into future runs
Agent run tracking — every spawn records duration, verdict, cost, iteration in task.agentRuns
Agent log browsing — stream NDJSON logs per agent, browse all sessions (completed + running)
Typed agent protocol — structured  blocks parsed by the orchestrator
tmux integration — resilient background runs with dead session detection and auto-cleanup
CLI overrides — override any config value at runtime via flags
Zero external deps for the board — pure Node.js, no database

Architecture

src/
├── cli.ts                  # CLI entry point (~50 commands)
├── config.ts               # constellation.json loader + merging
├── tmux.ts                 # tmux session management (dead session detection)
├── ui/
│   └── Dashboard.tsx        # Ink-powered live dashboard
├── adapters/
│   ├── types.ts            # AgentAdapter interface
│   ├── claude-cli.ts       # Claude Code CLI adapter
│   ├── codex-cli.ts        # OpenAI Codex CLI adapter
│   └── copilot-cli.ts      # GitHub Copilot CLI adapter
├── orchestrator/
│   └── procyon.ts          # Pipeline driver (sequential + parallel dispatch)
├── board/
│   ├── types.ts            # Board/Task/Subtask types, state machine
│   ├── state.ts            # Board I/O, conflict detection, pre-PR checks
│   ├── pipeline.ts         # Agent prompts, verdicts, dispatch, PR creation
│   ├── format.ts           # Output formatting
│   └── dashboard.ts        # Live terminal dashboard
└── agents/
    ├── spica.md            # Task optimizer prompt
    ├── vega.md             # Planner prompt
    ├── antares.md          # Devil's advocate prompt
    ├── deneb.md            # Spec validator prompt
    ├── rigel.md            # Developer prompt
    ├── polaris.md          # Tester prompt
    └── altair.md           # Reviewer prompt

Contributing

Fork the repository
Create a feature branch (git checkout -b feat/my-feature)
Commit your changes (git commit -m 'feat: add my feature')
Push to the branch (git push origin feat/my-feature)
Open a Pull Request

Please follow Conventional Commits for commit messages.

License

Apache-2.0

Built by @AndurilCode

Name		Name	Last commit message	Last commit date
Latest commit History 178 Commits
bin		bin
docs/exploration		docs/exploration
references		references
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Constellation ⭐

Pipeline

How It Works

Requirements

Installation

Quick Start

Commands

Dashboard

Supervised Mode

Pipeline

Session Management (tmux)

Board

Subtasks

Pipeline Control (Advanced)

Configuration

Agent Config Fields

Config Resolution Order

Adapters

Writing a Custom Adapter

Task States

Key Features

Architecture

Contributing

License

About

Uh oh!

Releases

Packages

Contributors 2

Languages

License

AndurilCode/constellation

Folders and files

Latest commit

History

Repository files navigation

Constellation ⭐

Pipeline

How It Works

Requirements

Installation

Quick Start

Commands

Dashboard

Supervised Mode

Pipeline

Session Management (tmux)

Board

Subtasks

Pipeline Control (Advanced)

Configuration

Agent Config Fields

Config Resolution Order

Adapters

Writing a Custom Adapter

Task States

Key Features

Architecture

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages

Packages