API Reference

Commander has two layers of API surface. Most apps only need Layer 1.

Layer 1 — Public integration (start here)

Surface	Package / entry	Best for
CLI	commander · packages/core/src/cliEntry.ts	Terminal, scripts, CI
TypeScript SDK	@commander/sdk → CommanderClient	Embed in Node apps
HTTP API	Server :4000	Polyglot clients, Web Console
Python SDK	commander-ai (HTTP client)	Python against the API server

TypeScript SDK

import { CommanderClient, createClient } from '@commander/sdk';

const client = new CommanderClient({ provider: 'openai' });
await client.connect();
const result = await client.run('audit this repo');
console.log(result.status, result.summary);
await client.disconnect();

// or
const c = await createClient();
await c.run('explain the architecture');
await c.disconnect();

Method	Role
connect / disconnect	Lifecycle
run(task)	Full execution → ExecutionResult
plan(task)	Deliberation only
onEvent(handler)	Stream agent/tool events
createAgent / memory helpers	Advanced session control

npm status: packages are monorepo-first; public publish is in progress. See Agent SDK.

HTTP (server)

curl http://localhost:4000/health
curl http://localhost:4000/metrics

curl -X POST http://localhost:4000/execute \
  -H "Authorization: Bearer $COMMANDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"analyze this repository","mode":"plan"}'

Architecture V2 durable API: POST /v1/runs — see V2 Migration.

Python

from commander import CommanderClient
# thin httpx client → API server

Python SDK.

---

Layer 2 — Runtime orchestration components

These modules power deliberation, budgeting, memory, and verification inside @commander/core. Use them when extending the runtime — not for normal app integration.

Component	Purpose
Task Complexity Analyzer	Score task → recommend topology
Adaptive Orchestrator	Multi-agent plan + coordination
Token Budget Allocator	Budget split across agents
Three-Layer Memory	Working · episodic · long-term
Reflection Engine	Post-run evaluation
Consensus Checker	Multi-model votes for high risk
Inspector Agent	Health / issue detection

When to use Layer 2

• Building a custom topology or planner
• Research / instrumentation of memory and consensus
• Tests that isolate a single subsystem

When not to use Layer 2

• Product features that only need “run this task” → use CommanderClient
• Remote multi-language clients → use HTTP

Minimal Layer 2 example

import {
  TaskComplexityAnalyzer,
  AdaptiveOrchestrator,
  TokenBudgetAllocator,
} from '@commander/core';

const analyzer = new TaskComplexityAnalyzer();
const complexity = analyzer.analyze({
  id: 'task-1',
  description: 'Build distributed logging system',
  riskLevel: 'high',
});

const allocator = new TokenBudgetAllocator({ baseBudget: 100_000 });
const budget = allocator.allocate(
  complexity.recommendedTopology,
  complexity.score,
  3,
);

const orchestrator = new AdaptiveOrchestrator();
orchestrator.registerAgent({
  id: 'lead',
  name: 'Lead',
  role: 'architect',
  capabilities: [],
});

const plan = orchestrator.createPlan(
  [{ id: 'task-1', description: '...', complexity: complexity.score }],
  complexity.recommendedTopology,
);

Global accessors

Some components expose process singletons (used by the runtime/SDK helpers):

• getGlobalTaskComplexityAnalyzer()
• getGlobalAdaptiveOrchestrator()
• getGlobalTokenBudgetAllocator()
• getGlobalThreeLayerMemory()
• getGlobalReflectionEngine()
• getGlobalConsensusChecker()
• getGlobalInspectorAgent()

Prefer CommanderClient unless you are sure you need process-wide shared state.

---

Architecture depth

Subsystem design (not method lists): Architecture overview, Agent runtime, Verification, Security.

Related guides

• CLI commands
• Web Console
• Cookbook