{"_id":"@citadel-labs/citadel","name":"@citadel-labs/citadel","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@citadel-labs/citadel","version":"0.1.0","description":"Multi-agent orchestration system — cold-start, hub-and-spoke coordination for autonomous LLM Citizens","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"citadel":"dist/cli/index.js"},"engines":{"node":">=20.0.0"},"os":["darwin","linux","win32"],"scripts":{"build":"tsc","dev":"tsc --watch","lint":"eslint src/","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","test:e2e":"npm run build && vitest run src/__tests__/cli-e2e/","prepublishOnly":"npm run build","version:patch":"npm version patch -m 'chore(release): v%s'","version:minor":"npm version minor -m 'chore(release): v%s'","version:major":"npm version major -m 'chore(release): v%s'","changelog":"git log --pretty=format:'* %s (%h)' $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~20)..HEAD","release:patch":"npm run lint && npm test && npm run version:patch && git push && git push --tags","release:minor":"npm run lint && npm test && npm run version:minor && git push && git push --tags","prepare":"husky"},"keywords":["citadel","agent","orchestration","llm","multi-agent"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/citadel-labs/citadel.git"},"publishConfig":{"access":"public"},"dependencies":{"chokidar":"^5.0.0","commander":"^14.0.3","nanoid":"^5.1.6","proper-lockfile":"^4.1.2","yaml":"^2.8.2"},"devDependencies":{"@types/node":"^25.3.5","@types/proper-lockfile":"^4.1.4","@vitest/coverage-v8":"^4.0.18","eslint":"^10.0.2","husky":"^9.1.7","typescript":"^5.9.3","typescript-eslint":"^8.56.1","vitest":"^4.0.18"},"_id":"@citadel-labs/citadel@0.1.0","gitHead":"441d7816984650d0760896c6e6fa9efb8ffecce4","bugs":{"url":"https://github.com/citadel-labs/citadel/issues"},"homepage":"https://github.com/citadel-labs/citadel#readme","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-0MGSXoB4BPyWwV4yKNNBSrJQZQ3qAlMCUL3N/3lmFZfv56yj/AiNuI9CY0szPGZHVLL1qHj+8EpgGgCMXns6YQ==","shasum":"da8668ed83e37ae07be3ef43c7f173cc73087737","tarball":"https://registry.npmjs.org/@citadel-labs/citadel/-/citadel-0.1.0.tgz","fileCount":307,"unpackedSize":676910,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD9fmsYvNYzOuT+lbRR0CONonW+DxZTcAjyqRX11zT6ZAIhAMKH/e3VKZlG2opRHXLNWKZ301MOEej8oo8Oh9fwhJvN"}]},"_npmUser":{"name":"stuart-rimel","email":"stuart.rimel@gmail.com"},"directories":{},"maintainers":[{"name":"stuart-rimel","email":"stuart.rimel@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/citadel_0.1.0_1772875433639_0.5253170338340774"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-07T09:23:53.536Z","0.1.0":"2026-03-07T09:23:53.790Z","modified":"2026-03-07T09:23:53.959Z"},"maintainers":[{"name":"stuart-rimel","email":"stuart.rimel@gmail.com"}],"description":"Multi-agent orchestration system — cold-start, hub-and-spoke coordination for autonomous LLM Citizens","homepage":"https://github.com/citadel-labs/citadel#readme","keywords":["citadel","agent","orchestration","llm","multi-agent"],"repository":{"type":"git","url":"git+https://github.com/citadel-labs/citadel.git"},"bugs":{"url":"https://github.com/citadel-labs/citadel/issues"},"license":"MIT","readme":"# CITADEL\n\nCold-start, hub-and-spoke orchestration for autonomous LLM agents.\n\nCITADEL 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.\n\n## How It Works\n\n```\nCommander (you)\n    |  issues orders via CLI\n    v\nFirst Officer (persistent LLM agent, agent-agnostic)\n    |  selects archetype, mints citizen_id, writes Mail\n    v\nCourier (daemon)\n    |  watches filesystem, manages worktrees, spawns Citizens\n    v\nCitizens (cold-start LLM agents in isolated git worktrees)\n    |  read Mail, do work, write Tribute\n    v\nFirst Officer receives Tribute, validates, broadcasts, retries or escalates\n```\n\n## Install\n\n```bash\nnpm install -g @citadel-labs/citadel\n```\n\nRequires Node.js v20+. Works on macOS, Linux, and Windows.\n\n## Quick Start\n\n```bash\ncitadel init my-project\ncd my-project\n\ncitadel outpost register --slug api-gateway --path ../api-gateway\ncitadel start\ncitadel dispatch --outpost api-gateway --task \"Implement GET /health endpoint\"\ncitadel status\ncitadel tribute --task <task-id>\ncitadel trace --task <task-id>\n```\n\nSee [Getting Started](docs/getting-started.md) for a full walkthrough.\n\n## CLI Reference\n\n| Command | Description |\n|---|---|\n| `citadel init [dir]` | Scaffold workspace |\n| `citadel start [--agent <runtime>]` | Boot the First Officer |\n| `citadel stop` | Graceful shutdown |\n| `citadel status` | Session info and outpost overview |\n| `citadel outpost register --slug <name> --path <path>` | Register a repo |\n| `citadel dispatch --outpost <slug> --task <text>` | Assign a task |\n| `citadel note --outpost <slug> --body <text>` | Send guidance |\n| `citadel resolve --task-id <id> --action <action>` | Resolve escalation |\n| `citadel command retry --task <id>` | Force retry |\n| `citadel tribute --task <id>` | View tribute attempts |\n| `citadel trace --task <id>` | Full event timeline |\n| `citadel reset [--hard]` | Clear state (hard removes `.citadel/`) |\n| `citadel worktree list/prune` | Manage worktrees |\n\nFull details: [CLI Reference](docs/cli-reference.md)\n\n## Architecture\n\n| Role | What It Does | Writes |\n|---|---|---|\n| **Commander** | Issues orders, reviews Broadcasts | Command Beads |\n| **First Officer** | Orchestrates -- dispatch, retry, escalate | Mail Beads (downward) |\n| **Courier** | Watches filesystem, spawns Citizens | Nudge Beads only |\n| **Citizens** | Execute tasks in isolated worktrees | Tribute + Mail (upward) |\n\nAll 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](docs/architecture.md)\n\n## Workspace Layout\n\n```\nmy-project/\n  courier.config.yaml\n  .citadel/\n    identity.jsonl\n    outposts.json\n    nudges.jsonl\n    commands/\n    logs/\n  grand-archives/\n    first-officer/\n    archetypes/\n    shared/\n  outposts/\n```\n\n## Configuration\n\n`courier.config.yaml` at the workspace root:\n\n```yaml\ncitadel_root: .\npoll_interval_ms: 500\ndebounce_ms: 200\ndefault_max_citizens: 3\ncitizen_timeout_seconds: 1800\nlog_level: INFO\n```\n\nFull details: [Configuration](docs/configuration.md)\n\n## Design Principles\n\n- **Mail is the universal envelope.** Every activation begins with a Mail Bead.\n- **Beads are state. Nudges are signals.** Full state from Mail + Tribute only.\n- **Write authority is strict.** FO writes down. Citizens write up. Courier writes Nudge only.\n- **Writes are serialized via lockfiles.** Cross-platform safe.\n- **Identity persists. Sessions are cattle.** Kill and restart freely.\n- **Everything communicates via files.** No PIDs, no pipes, no tight coupling.\n\n## Development\n\n```bash\ngit clone <repo>\ncd citadel\nnpm install\nnpm run build\nnpm test\n```\n\nSee [Contributing](docs/contributing.md) for full guidelines.\n\n## Current Status\n\nMilestones 0-3 implemented.\n\n- **M0** -- Scaffold: Types, Grand Archives, CLI entrypoint\n- **M1** -- Foundation: Bead I/O, Courier, WorktreeManager, ProcessRegistry, CLI\n- **M2** -- Labor & Tribute: First Officer, Citizen lifecycle, retry, escalation\n- **M3** -- Broadcast & Routing: Dependencies, relay, task reports, webhook\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-53ce6007ab36a0a56f5a50d950693c9a"}