Citadel: Multi-Tier Routing and Campaign Persistence for Claude Code Agent Orchestration

Hook

Claude Code agents forget everything between sessions and bottleneck on sequential execution. Citadel fixes both problems by treating agent work as persistent campaigns with parallel execution—reducing overhead to 2.5% of session cost while enabling true multi-agent coordination.

Context

AI coding assistants like Claude Code and Codex excel at generating code within a single session, but they suffer from two critical scaling problems. First, every new session starts cold—the agent has no memory of previous architectural decisions, patterns, or mistakes, forcing developers to re-explain context repeatedly. Second, these agents operate sequentially on a single codebase, creating bottlenecks when refactoring requires changes across dozens of files or multiple architectural layers simultaneously.

Citadel emerged from the observation that enterprise engineering workflows aren't single-session tasks—they're campaigns that span days or weeks, require coordination across multiple concerns, and accumulate learnings over time. While frameworks like LangChain and CrewAI provide primitives for building custom agent systems, they require substantial orchestration logic. Citadel takes a different approach: it's an opinionated harness specifically for Claude Code that provides routing intelligence, session persistence, parallel coordination, and safety controls out of the box. It assumes you're already using Claude Code on real codebases and have hit the limits of single-session, sequential agent execution.

Technical Insight

Citadel's core innovation is its four-tier routing system that progressively escalates classification complexity. When you invoke /do refactor authentication layer, the system first attempts zero-cost regex pattern matching against known command templates. If that fails, it checks filesystem state (has this campaign been worked on before?). Only then does it move to keyword-based lookup against the six bundled skills (debug, refactor, test, document, integrate, deploy). The LLM-based classification tier activates last, and only when the previous three tiers can't resolve intent. This defers the most expensive operation—sending your request to Claude for semantic analysis—until absolutely necessary.

The routing hierarchy mirrors agent complexity. Skills handle single-concern tasks ("add error handling to auth.js"). Marshals coordinate multiple skills for cross-cutting concerns ("refactor authentication across frontend and backend"). Archons manage architectural decisions that span subsystems. Fleet mode is where things get interesting: it spins up parallel agents in isolated git worktrees, each operating on a separate branch. A discovery relay broadcasts findings between agents, so when one agent discovers a shared dependency, others can adapt their execution plans mid-flight.

Here's what campaign persistence looks like in practice:

// After running /do refactor authentication layer
// Citadel creates .citadel/campaigns/auth-refactor/
// ├── manifest.json          # Goal, scope, current phase
// ├── decisions.log          # Architectural choices made
// ├── patterns.json          # Code patterns discovered
// └── cost-tracking.json     # Token usage per session

// Next day, you run /do continue
// Citadel loads the campaign manifest:
{
  "campaignId": "auth-refactor-2024-01",
  "goal": "Migrate from JWT to session-based auth",
  "progress": {
    "completed": ["backend token validation", "middleware updates"],
    "inProgress": "frontend cookie handling",
    "blocked": ["Redis session store integration"]
  },
  "context": {
    "keyDecisions": [
      "Using httpOnly cookies to prevent XSS",
      "Session TTL set to 7 days with sliding window"
    ],
    "dangerZones": ["logout race condition in multi-tab scenarios"]
  }
}

The agent resumes with full context—no re-explanation needed. Campaign artifacts live in .citadel/ and persist across runtime restarts, solving the cold-start problem that plagues single-session tools.

Lifecycle hooks provide 14 interception points with 22 safety gates. The consent system is particularly clever: on first encounter with an external action (npm install, git push, API call), you choose between always-ask, session-allow, or auto-allow. This creates a graduated safety model—strict for unfamiliar operations, permissive for trusted patterns. The circuit breaker monitors error rates and automatically pauses execution if failure thresholds are exceeded, preventing runaway agent loops that burn through API quotas.

Fleet coordination deserves deeper examination because it solves a real architectural problem: how do you parallelize agent work on an interconnected codebase without conflicts? Citadel's approach is git-native:

// /do fleet "migrate API endpoints to v2 spec"
// Citadel analyzes scope, identifies 8 independent endpoint files
// Creates isolated worktrees:
// .citadel/fleet/agent-1/ → users-endpoint branch
// .citadel/fleet/agent-2/ → posts-endpoint branch
// .citadel/fleet/agent-3/ → auth-endpoint branch
// ...

// Discovery relay broadcasts between agents:
{
  "agentId": "agent-2",
  "discovery": {
    "pattern": "All v2 endpoints need new error schema",
    "code": "class V2Error { statusCode, message, details, traceId }",
    "impact": "shared-dependency"
  }
}
// Other agents receive broadcast, adapt their implementations

Each agent operates in isolation until merge time, when Citadel consolidates branches with conflict detection. The discovery relay prevents duplicate work and propagates learnings in near real-time.

The /evolve command implements an autonomous improvement loop. After each session, Citadel scores outcomes (tests passing, code quality metrics, developer acceptance), generates hypotheses about what could improve ("routing misclassified 'deploy' as 'test' skill"), validates hypotheses against historical data, and updates its pattern library. These learnings transfer across campaigns—patterns discovered during authentication refactoring inform database migration work weeks later. This compounds over time, creating a harness that genuinely gets better with use rather than remaining static.

Gotcha

Citadel is tightly coupled to Claude Code and Codex runtimes—it's not a general-purpose agent framework. If you're using GPT-4, Gemini, or local models, this won't work without substantial modification. The architecture assumes specific runtime behaviors (how Claude Code handles file operations, context windows, tool calling) that don't generalize. You're locked into the Anthropic ecosystem.

The 545 GitHub stars signal early adoption phase. While the architecture is sophisticated, production edge cases likely haven't been battle-tested at scale. Campaign persistence relies on filesystem state—what happens when multiple developers run overlapping campaigns on the same codebase? The documentation doesn't address collaborative workflows or conflict resolution beyond git mechanics. Fleet mode's discovery relay is eventually consistent, which could lead to agents making decisions on stale information during high-churn operations. The lack of TypeScript implementation is surprising for a tool targeting engineering workflows—JavaScript's runtime typing increases the risk of orchestration bugs in complex multi-agent scenarios. Error messages and debugging support for routing misclassifications or stuck campaigns aren't well documented, which could lead to frustrating troubleshooting sessions when the harness behaves unexpectedly.

Verdict

Use if: You're already running Claude Code or Codex on production codebases and experiencing session amnesia (re-explaining architecture daily), hitting parallelization bottlenecks (large refactors take forever sequentially), or burning API budget on redundant classification (every request goes straight to LLM). Citadel shines when you have multi-day engineering campaigns that need persistent context and coordination across multiple concerns. Skip if: You're new to AI coding assistants (learn Claude Code directly first—adding orchestration before understanding base capabilities creates confusion), need a general-purpose agent framework for custom workflows (CrewAI or LangGraph offer more flexibility), work outside the Claude/Codex ecosystem (tight coupling makes this unusable), or operate in collaborative environments where multiple developers need concurrent campaign access (single-filesystem persistence model doesn't address multi-user coordination).