Circe

Composable multi-agent orchestration framework built on the Claude Agent SDK. ~2K lines of source, 5 dependencies.

Five building blocks — Pipeline, Loop, Parallel, Contract, Sprint — snap together like LEGO to create complex agent workflows. Runs in the Claude Code ecosystem with OAuth (free) or API key.

Originally inspired by Anthropic's harness design for long-running apps. Works for any agent composition pattern — not just adversarial loops.

Install

npm install @hham21/circe

Requires Node.js 22+ and Claude authentication (API key or OAuth):

# API key
export ANTHROPIC_API_KEY=sk-ant-...

# Or OAuth (Claude App, Claude Code, etc.)
# The Agent SDK detects OAuth tokens automatically

Quick Start

import { Agent, Loop, Session } from "@hham21/circe";

const generator = new Agent({
  name: "generator",
  prompt: "Build the app based on the spec or QA feedback.",
  model: "claude-sonnet-4-6",
});

const evaluator = new Agent({
  name: "evaluator",
  prompt: "Test the app. FAIL with feedback if issues found.",
  model: "claude-opus-4-6",
});

const loop = new Loop(generator, evaluator, { maxRounds: 3 });

await new Session({ outputDir: "./output", logLevel: "debug" })
  .run(() => loop.run("Build a retro game maker"));

See examples/ for 14 progressive examples (npx tsx examples/01-single-agent.ts).

Concepts

Agents

import { Agent, agent } from "@hham21/circe";

// Factory function (simple)
const reviewer = agent({
  name: "reviewer",
  prompt: "Review code for bugs.",
  tools: ["Read", "Grep"],
});

// Class (fine-grained control)
const evaluator = new Agent({
  name: "evaluator",
  prompt: "Strict QA engineer.",
  model: "claude-opus-4-6",
  tools: ["Read", "Bash"],
  disallowedTools: ["Write"],
  skills: ["qa"],
  contextStrategy: "reset",
});

All Claude Agent SDK built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Agent) are available by default. Restrict with tools (allowlist) or disallowedTools (blocklist). Set model per agent to control cost/capability.

Structured Output

Use Zod schemas to validate agent input and output:

import { Agent } from "@hham21/circe";
import { z } from "zod";

const planner = new Agent({
  name: "planner",
  prompt: "Break the spec into features.",
  outputSchema: z.object({
    features: z.array(z.object({
      name: z.string(),
      description: z.string(),
    })),
  }),
});

const result = await planner.run("Build a todo app");
// result is typed and validated against the schema

Full Agent Options

Option	Type	Description
name	string	Agent name (required)
prompt	string	System prompt (required)
model	string	Claude model ID
tools	string[]	Allowed tools (allowlist)
disallowedTools	string[]	Blocked tools (blocklist)
skills	string[]	On-demand prompt templates
mcpServers	Record<string, unknown>	MCP server config
contextStrategy	"compaction" | "reset"	Context management
inputSchema	ZodSchema	Validate input
outputSchema	ZodSchema	Validate & type output
permissionMode	string	Tool permission mode
continueSession	boolean	Resume previous session
costPerMTokens	{ input, output }	Custom cost rates
timeout	number	Max execution time (ms)

Orchestrators

Five composable building blocks, all generic: Runnable<TIn, TOut>.

Orchestrator	Purpose	Example
Pipeline	Sequential execution	new Pipeline(planner, builder) or pipe(a, b, c)
Loop	Repeat until condition	new Loop(gen, eval, { maxRounds: 3, stopWhen: ... })
Parallel	Concurrent execution	new Parallel(frontend, backend)
Contract	Pre-build negotiation	new Contract(proposer, reviewer, { isAccepted: ... })
Sprint	Feature decomposition	new Sprint(runner)

Loop and Contract return producer output on success (the content, not the evaluation). Access evaluation via .lastEvaluatorResult. All orchestrators expose .lastMetrics for cost tracking.

Parallel returns a Record<string, { status: "fulfilled", value } | { status: "rejected", error }>. Sprint returns { sprintResults: TOut[] }.

Compose freely:

import { pipe, map } from "@hham21/circe";

// Type-safe pipeline — compiler checks that output types chain correctly
pipe(planner, new Loop(generator, evaluator, { maxRounds: 3 }));

// With negotiation
pipe(planner, new Contract(proposer, reviewer), new Loop(generator, evaluator));

// map() wraps a pure function as a Runnable for inline transforms between steps
pipe(
  planner,
  map((spec) => ({ ...spec, features: spec.features.slice(0, 3) })),
  new Loop(generator, evaluator, { maxRounds: 3 }),
);

Events & Observability

EventBus tracks cost, emits lifecycle events, and enforces budget limits across all orchestrators:

import { EventBus } from "@hham21/circe";

const bus = new EventBus({ maxCost: 5.0 }); // throws if exceeded

bus.on("agent:done", (e) => console.log(`${e.agent}: $${e.cost.toFixed(4)}`));
bus.on("round:done", (e) => console.log(`Round ${e.round} complete`));
bus.on("retry", (e) => console.log(`Retrying ${e.agent} (${e.attempt}/${e.maxAttempts})`));

const loop = new Loop(generator, evaluator, {
  maxRounds: 3,
  eventBus: bus,
});

await loop.run(input);
console.log(bus.getCostSummary()); // { total: 1.23, perAgent: { generator: 0.8, evaluator: 0.43 } }

Event types: agent:start/done/error, step:start/done/error (Pipeline), round:start/done/error (Loop/Contract), branch:start/done/error (Parallel), sprint:start/done/error (Sprint), retry, pipeline:done, cost:pressure, cost:warning.

Graduated Cost Control

Beyond the hard maxCost limit, Circe emits a costPressure signal (0.0–1.0 fraction of budget consumed) on every cost tick. Orchestrators check session.shouldStop between steps so workflows can exit cleanly when the budget tightens instead of crashing mid-round. Configure thresholds via Session.costPolicy (see Session below). round:done events also carry costByAgent for per-agent attribution.

Retry

All orchestrators accept a retryPolicy for automatic retries with exponential backoff:

const loop = new Loop(generator, evaluator, {
  maxRounds: 3,
  retryPolicy: { maxRetries: 2 },
  eventBus: bus,
});

Defaults: exponential backoff (1s-60s), skips non-retryable errors (400, 401, 403). Customize with backoff and shouldRetry functions.

Session

Session eliminates boilerplate. It auto-creates the output directory, sets up logging, initializes the skill registry, and cleans up when done. Context propagates through any orchestrator nesting via AsyncLocalStorage.

import { Session } from "@hham21/circe";

const session = new Session({
  outputDir: "./output/my-app",
  logLevel: "debug", // "silent" | "info" | "debug" | "trace"
  maxCost: 5.0,      // hard budget in USD (throws at 100%)
  costPolicy: {      // graduated pressure thresholds (fractions of maxCost)
    warn: 0.7,       // emits cost:warning event at 70%
    softStop: 0.9,   // sets session.shouldStop at 90% (orchestrators exit cleanly)
    hardStop: 1.0,   // throws Error at 100%
  },
  agentCostLimits: { generator: 2.0, evaluator: 1.0 }, // per-agent USD caps
});
await session.run(() => pipeline.run("Build a todo app"));

console.log(`Duration: ${session.duration.toFixed(1)}s`);

Without Session, you can still use the global setters (setFormatter, setWorkDir, setSkillRegistry) directly.

Tools

MCP servers are supported via the mcpServers parameter on agents:

const agent = new Agent({
  name: "researcher",
  prompt: "Research the topic.",
  mcpServers: {
    "web-search": { command: "npx", args: ["-y", "@anthropic-ai/mcp-web-search"] },
  },
});

Skills

Skills are on-demand prompt templates. Agents load them when needed:

const evaluator = agent({
  name: "evaluator",
  prompt: "QA engineer.",
  skills: ["qa"],
});

The agent sees a skill list in its prompt and calls use_skill("qa") to load the full methodology.

Context Strategy

Strategy	When to use
compaction (default)	Most cases. Agent SDK auto-summarizes context.
reset	Weaker models or long Sprint-based builds. Clean context per sprint.

Handoff Schemas

Zod schemas for structured agent-to-agent data passing:

• ProductSpecSchema — Planner output
• BuildResultSchema — Generator output
• QAReportSchema — Evaluator output

CLI

# Run a workflow file
circe run workflow.js -i "prompt or spec file" -v

# Skill management
circe skills list
circe skills create my-skill
circe skills info my-skill
circe skills delete my-skill

Architecture

Session Layer      Session (AsyncLocalStorage context propagation)
CLI Layer          circe run, skills
Orchestration      Pipeline, Loop, Parallel, Sprint, Contract
Agent Layer        Agent, agent(), Handoff, Context Strategy
Tool Layer         SDK built-ins, MCP servers, Skills

Development

npm install
npm test
npm run build