A small, extraction-friendly runtime for running role-based multi-agent workspaces on top of the official Claude Agent SDK and Codex SDK.
This package gives us one unified protocol for:
- defining role agents and coordinator roles
- accepting a workspace-level user turn and routing it across the team
- modeling workspace members, public activity, and claim policies
- declaring template-level workflows with stages, nodes, edges, artifacts, and completion rules
- observing task lifecycle as events
- validating generated artifacts in end-to-end tests
The repository now contains:
- a TypeScript reference implementation
- a Rust protocol/core implementation intended for embedding into Cteno
The current adapters are:
ClaudeAgentWorkspacefor Anthropic Claude Agent SDKCodexSdkWorkspacefor OpenAI Codex SDK
The protocol is intentionally generic enough to support a future Cteno-native adapter.
@cteno/multi-agent-runtime treats a workspace as:
- one coordinator role
- multiple named workspace members
- explicit role dispatches such as
prd,finance, orscout - optional claim-based assignment rules
- a unified event stream for
workspace,member,activity,dispatch,message,tool.progress, andresult
That maps well onto Claude's session-centric model while keeping our authoring model role-centric.
A software delivery workspace.
Roles:
pmprdarchitectcodertesterreviewer
Typical outcome:
- PRDs
- implementation notes
- code changes
- test reports
A one-person company staffed by specialist digital operators.
Roles:
ceofinancetaxadminrecruiter
Typical outcome:
- operating checklists
- finance docs
- tax prep handoff notes
- admin SOPs
A research-oriented workspace for scouting, synthesis, and lightweight experiment framing.
Roles:
leadscoutexperimentercritic
Typical outcome:
- sourced briefs
- comparison notes
- experiment outlines
- research critiques
A governance-style multi-agent template for planning, review, execution, oversight, and release coordination.
Roles include:
shangshuzhongshumenxiagongbuhubulibuxingbubingbu
npm install @anthropic-ai/claude-agent-sdk @openai/codex-sdkThis package currently assumes:
- Node
>=20 - a working Claude Code / Claude Agent SDK environment
- a working Codex CLI / Codex SDK environment
- local Claude authentication already configured on the machine running the tests
- local Codex authentication already configured on the machine running the tests
import {
ClaudeAgentWorkspace,
createClaudeWorkspaceProfile,
createCodingStudioTemplate,
instantiateWorkspace,
} from '@cteno/multi-agent-runtime';
const workspace = new ClaudeAgentWorkspace({
spec: instantiateWorkspace(
createCodingStudioTemplate(),
{
id: 'demo-coding-studio',
name: 'Demo Coding Studio',
cwd: process.cwd(),
},
createClaudeWorkspaceProfile(),
),
});
workspace.onEvent(event => {
console.log(event.type, event);
});
await workspace.start();
const turn = await workspace.runWorkspaceTurn({
message:
'We need a short PRD for a group-chat mention feature. Please create it at 10-prd/group-mentions.md with sections for Goal, User Story, Scope, Non-Goals, and Acceptance Criteria.',
});
console.log(turn.plan);
console.log(turn.dispatches[0]?.status);
console.log(turn.dispatches[0]?.resultText);
await workspace.close();import {
CodexSdkWorkspace,
createCodingStudioTemplate,
createCodexWorkspaceProfile,
instantiateWorkspace,
} from '@cteno/multi-agent-runtime';
const workspace = new CodexSdkWorkspace({
spec: instantiateWorkspace(
createCodingStudioTemplate(),
{
id: 'demo-codex-coding-studio',
name: 'Demo Codex Coding Studio',
cwd: process.cwd(),
},
createCodexWorkspaceProfile({
model: 'gpt-5.1-codex-mini',
}),
),
skipGitRepoCheck: true,
approvalPolicy: 'never',
sandboxMode: 'workspace-write',
});
await workspace.start();
const turn = await workspace.runWorkspaceTurn({
message:
'We need a short PRD for a group-chat mention feature. Please create it at 10-prd/group-mentions.md with sections for Goal, User Story, Scope, Non-Goals, and Acceptance Criteria.',
});
console.log(turn.plan);
console.log(turn.dispatches[0]?.status);
console.log(turn.dispatches[0]?.resultText);
await workspace.close();The runtime now supports role-level provider mixing through HybridWorkspace.
Use this when you want one workspace where:
- Claude-owned roles handle planning, coordination, or status tracking
- Codex-owned roles handle coding and validation
- the event stream still looks like one workspace
The key requirement is:
- run a spec whose resolved providers span more than one provider
- set explicit
provideronly where a role or workflow node differs from the workspace default
Resolution order is now:
- template-level default provider/model
- profile-level override of the template default
- role-level provider/model override
- workflow-node-level provider/model override for dispatches created from that node
If the final resolved providers span more than one provider, instantiateWorkspace() now infers spec.provider = 'hybrid'.
There is a reference TypeScript example at src/examples/hybridClaudeCodex.ts, runnable with:
npm run smoke:hybrid -- /absolute/workspace/path "your task here"Takes a single workspace-level user message, lets the coordinator interpret it, emits public workspace activity, and returns the routed role dispatches.
This is now the primary API for the full multi-agent effect:
- one user message enters the workspace
- the coordinator decides who should claim it
- the selected member(s) run through the provider adapter
- public activity is emitted for user messages, coordinator responses, claims, progress, and delivery
Queues a task for a role and returns immediately with the local dispatch record.
Queues a task and waits until:
- the dispatch reaches a terminal state
- Claude returns final result text for the delegated task, when available
This remains useful for deterministic low-level tests and adapter debugging.
Subscribes to the workspace event stream.
Useful event types:
workspace.startedworkspace.initializedworkspace.state.changedmember.registeredmember.state.changedactivity.publisheddispatch.claimed
Templates can now carry a declarative workflow in addition to roles and claim policy. The runtime does not yet execute every workflow node natively, but the protocol and built-in templates now preserve the structure needed for reliable loops and gates.
Current workflow objects:
workflow.modeworkflow.stagesworkflow.nodesworkflow.edgesartifactscompletionPolicy
Current node vocabulary:
announceassignclaimshellevaluatereviewbranchloopartifactcommitrevertmergecomplete
That lets us express patterns such as:
- coding loop:
claim -> prd -> review -> architecture -> implement -> test -> review -> complete - autoresearch loop:
frame -> claim evidence -> shell run -> evaluate -> keep/discard -> loop - governance flow:
draft -> review -> dispatch -> execute -> compliance -> final review - workflow nodes may now optionally override provider/model for the role they dispatch
dispatch.queueddispatch.starteddispatch.progressdispatch.completeddispatch.resulttool.progressresulterror
npm install
npm run typecheck
npm run buildHelpful commands:
npm test
npm run cleancd rust
cargo testRust crates:
multi-agent-protocolmulti-agent-runtime-coremulti-agent-runtime-claudemulti-agent-runtime-codexmulti-agent-runtime-cteno
Run Rust live provider checks explicitly:
cd rust
cargo test -p multi-agent-runtime-claude --test live_claude_e2e -- --ignored --nocapture
cargo test -p multi-agent-runtime-codex --test live_codex_e2e -- --ignored --nocaptureThese are useful for manual exploration, but they are not our release-quality validation layer.
npm run smoke:coding
npm run smoke:opc
npm run smoke:autoresearchThese are the important ones.
They make real Claude calls and assert:
- the workspace initializes correctly
- the dispatch is queued, started, completed, and produces a final result
- the delegated role matches the expected role
- the expected file is actually generated
- the generated content matches template-specific acceptance checks
Run them individually:
npm run e2e:coding
npm run e2e:codex
npm run e2e:opc
npm run e2e:autoresearchRun the full suite sequentially:
npm run e2eChecks that:
- the
prdrole is used 10-prd/group-mentions.mdis created- the file contains
Goal,User Story,Scope,Non-Goals, andAcceptance Criteria
Checks that:
- the
CodexSdkWorkspaceadapter can reuse a role thread - the
prdrole writes10-prd/group-mentions.md - the generated PRD contains the expected sections
- the output is concise and implementation-oriented
Checks that:
- the
financerole is used company/10-finance/monthly-close-checklist.mdis created- the file contains monthly close sections for cash, invoices, subscriptions, payroll, tax prep, and KPIs
- the output is a real checklist with multiple actionable items
Checks that:
- the
scoutrole is used - the workspace emits multiple research progress events
research/10-scout/mention-patterns.mdis created- the brief includes
Implications for Cteno - the brief references tools like Slack and GitHub
- the brief includes at least three source links
Claude's public interface behaves more like:
- sessions
- subagents
- task lifecycle notifications
and less like a fully exposed graph runtime.
So this package keeps the runtime thin and practical:
WorkspaceSpecdefines the workspace and its rolesClaudeAgentWorkspaceadapts those roles into Claude subagents- dispatches are provider-neutral records in our protocol
- events are normalized before they reach callers
Role-task correlation is still FIFO:
- each
assignRoleTask()call queues a local dispatch - the next Claude
task_startedevent is matched to the next queued dispatch
This is reliable when the orchestrator is the only source of subagent launches. If we later allow autonomous, unrelated subagent launches in the same session, we should strengthen correlation beyond FIFO.
Current status for the Claude adapter:
- live dispatching works
- delegated role tasks produce normalized
dispatch.*events - final result text is attached back onto the dispatch as
resultText - all three built-in templates have passing live e2e coverage
Current status for the Rust side:
- provider-neutral protocol types implemented
- core dispatch lifecycle runtime implemented
- Cteno adapter traits and bootstrap flow implemented
cargo testpasses for protocol/core/cteno workspace
That makes this package good enough to continue hardening toward an open-source split, with Cteno integration as the next adapter layer.
See: