CITADEL

Cold-start, hub-and-spoke orchestration for autonomous LLM agents.

CITADEL coordinates multiple LLM "Citizens" across independent code repositories ("Outposts"). Agents don't idle -- they are summoned, work in isolated git worktrees, deliver Tribute, and go dark. Everything persists in append-only JSONL records called Beads. Sessions are ephemeral; state survives.

How It Works

Commander (you)
    |  issues orders via CLI
    v
First Officer (persistent LLM agent, agent-agnostic)
    |  selects archetype, mints citizen_id, writes Mail
    v
Courier (daemon)
    |  watches filesystem, manages worktrees, spawns Citizens
    v
Citizens (cold-start LLM agents in isolated git worktrees)
    |  read Mail, do work, write Tribute
    v
First Officer receives Tribute, validates, broadcasts, retries or escalates

Install

npm install -g @citadel-labs/citadel

Requires Node.js v20+. Works on macOS, Linux, and Windows.

Quick Start

citadel init my-project
cd my-project

citadel outpost register --slug api-gateway --path ../api-gateway
citadel start
citadel dispatch --outpost api-gateway --task "Implement GET /health endpoint"
citadel status
citadel tribute --task <task-id>
citadel trace --task <task-id>

See Getting Started for a full walkthrough.

CLI Reference

| Command | Description | |---|---| | citadel init [dir] | Scaffold workspace | | citadel start [--agent <runtime>] | Boot the First Officer | | citadel stop | Graceful shutdown | | citadel status | Session info and outpost overview | | citadel outpost register --slug <name> --path <path> | Register a repo | | citadel dispatch --outpost <slug> --task <text> | Assign a task | | citadel note --outpost <slug> --body <text> | Send guidance | | citadel resolve --task-id <id> --action <action> | Resolve escalation | | citadel command retry --task <id> | Force retry | | citadel tribute --task <id> | View tribute attempts | | citadel trace --task <id> | Full event timeline | | citadel reset [--hard] | Clear state (hard removes .citadel/) | | citadel worktree list/prune | Manage worktrees |

Full details: CLI Reference

Architecture

| Role | What It Does | Writes | |---|---|---| | Commander | Issues orders, reviews Broadcasts | Command Beads | | First Officer | Orchestrates -- dispatch, retry, escalate | Mail Beads (downward) | | Courier | Watches filesystem, spawns Citizens | Nudge Beads only | | Citizens | Execute tasks in isolated worktrees | Tribute + Mail (upward) |

All state lives in append-only JSONL Beads, written through appendBead() with lockfile serialization. Mail is the sole wake trigger. Nudges are disposable signals. Full details: Architecture

Workspace Layout

my-project/
  courier.config.yaml
  .citadel/
    identity.jsonl
    outposts.json
    nudges.jsonl
    commands/
    logs/
  grand-archives/
    first-officer/
    archetypes/
    shared/
  outposts/

Configuration

courier.config.yaml at the workspace root:

citadel_root: .
poll_interval_ms: 500
debounce_ms: 200
default_max_citizens: 3
citizen_timeout_seconds: 1800
log_level: INFO

Full details: Configuration

Design Principles

• Mail is the universal envelope. Every activation begins with a Mail Bead.
• Beads are state. Nudges are signals. Full state from Mail + Tribute only.
• Write authority is strict. FO writes down. Citizens write up. Courier writes Nudge only.
• Writes are serialized via lockfiles. Cross-platform safe.
• Identity persists. Sessions are cattle. Kill and restart freely.
• Everything communicates via files. No PIDs, no pipes, no tight coupling.

Development

git clone <repo>
cd citadel
npm install
npm run build
npm test

See Contributing for full guidelines.

Current Status

Milestones 0-3 implemented.

• M0 -- Scaffold: Types, Grand Archives, CLI entrypoint
• M1 -- Foundation: Bead I/O, Courier, WorktreeManager, ProcessRegistry, CLI
• M2 -- Labor & Tribute: First Officer, Citizen lifecycle, retry, escalation
• M3 -- Broadcast & Routing: Dependencies, relay, task reports, webhook

License

MIT