What if AI agents worked like a real team — proposing, debating, and refining ideas — instead of each working alone?
Today's AI agents are brilliant but lonely. Each one works in isolation: no colleagues to challenge its assumptions, no second opinion, nobody to ask "wait, did you think about…?" For simple tasks that's fine. For complex decisions — planning, engineering, strategy — a single agent is one-track-minded by design.
AgentWeave is an open-source runtime where multiple AI agents collaborate the way good human teams do:
- Propose — agents independently draft competing solutions, no groupthink.
- Critique — a reviewer agent challenges every proposal and finds the holes.
- Rebut — proposers defend their ideas and address the criticism.
- Synthesize — a lead agent combines the best of all sides into one decision.
- Human steer — at key moments, a human steps in to set direction ("prioritize sustainability", "cap the budget"), and the synthesis must honor it.
The result is more robust than any single agent's answer — not because the models are smarter, but because the process is: multiple perspectives, honest debate, human judgment where it matters most.
Status: pre-1.0 developer preview. The collaboration loop above now runs end to end against a real provider (Codex): agents independently propose, a reviewer critiques, a lead synthesizes and decomposes the plan into tasks, specialists execute in parallel, QA validates, and a human approves at explicit dashboard gates. A recent verified run took a one-sentence brief to a working web app with 20 completed tasks and 51 passing tests, with live per-agent token accounting in the dashboard throughout. Provider adapters also include Claude Code and a local Ollama path, the latter verified end to end through a full collaboration round (proposals, critique, synthesis, per-agent usage) on a locally hosted 8B model. The deterministic mock provider remains the credential-free path for demos and CI (see
demo/). Remaining reliability work is tracked in the v0.2 roadmap.
AgentWeave is an open-source runtime OS for collaborative AI agents. An agent is not an isolated chat session: it is an actor inside a durable, observable, and human-steerable system that can coordinate with other actors and safely resume after interruption.
The runtime owns the workstream, task graph, message delivery, provider session, workspace boundary, evidence, recovery, and approval points. Agents are replaceable workers; the runtime is the product.
This repository is pre-1.0 and currently focused on a single-host, Docker-first MVP for software-development workstreams. It is not production-hardened for untrusted multi-tenant deployment.
AgentWeave is an AI collaboration platform for solo founders and small teams. You define a goal, configure an AI team, and let agents autonomously collaborate, execute tasks, and deliver results — while you retain final approval. It is an AI workforce that lets one person accomplish work that traditionally required a team:
AgentWeave lets a solo founder run an AI team that plans, debates, executes, and delivers work — with dynamic collaboration, persistent execution, and human approval.
AgentWeave does not run a predefined workflow. Agents determine who should work on a task, which agent should collaborate with another, when to create additional tasks, how dependencies should evolve, and when to request review or assistance. The collaboration graph emerges during execution: a lead decomposes the goal into tasks at runtime, specialists pick up work in parallel, reviewers send findings back as new tasks, and a human can steer mid-run.
Agents decide how to collaborate. The runtime ensures collaboration remains reliable, observable, and controllable.
Agent evaluation and human acceptance are separate steps. A PM or evaluator agent may recommend that a workstream is complete, but the human remains the final acceptance authority — with approval gates, mid-execution steering, observable decisions, evidence and artifact inspection, and rejection that continues execution instead of ending it.
Delegate execution without surrendering control.
Providers are adapters behind one contract, so the model can follow the job: a strong reasoning model for planning and coordination, Codex for implementation, a local model via Ollama for lower-cost research, a fast model for QA validation. Adapters for Codex App Server, Claude Code, Ollama, and a deterministic mock are implemented today (see the capability matrix). Workstreams may route each role to a different provider and model while unconfigured roles inherit the workstream default.
Use the right model for the right agent.
A workstream is a persistent object, not an ephemeral chat session. PostgreSQL is the source of truth, NATS JetStream carries durable messages, and tasks, sessions, checkpoints, and evidence are persisted — so AI teams can execute long-running work without losing progress. Crash-atomic event publication and complete cross-worker recovery are still in progress (see the capability matrix).
Collaboration should scale with the task instead of charging full-team cost for every job: a simple task may need a single agent, a medium one an agent plus a reviewer, a complex one several specialists, and a high-risk decision the full loop — independent proposals, critique, synthesis, and human review. The goal is outcome quality relative to cost and latency, and it drives the current roadmap.
AgentWeave is built around a simple thesis: the innovation space of multiple collaborating agents can be larger than a single Agent ↔ Human conversation. Its central claim is deliberately narrow: the value of AgentWeave is not the number of agents it can orchestrate, but the quality of work those agents can accomplish together. The important difference is not merely using more model calls. Different agents can hold different roles, challenge assumptions, propose alternatives, divide the search space, and combine partial solutions before a human reviews the result.
This thesis is informed by research on multi-agent conversation, role-based collaboration, and debate. AutoGen presents flexible applications built from conversable agents, humans, and tools; CAMEL studies role-playing agents that cooperate with less continuous human steering; multi-agent debate reports gains in reasoning and factuality from independent proposals and critique; and MetaGPT shows how role-specialized workflows can structure complex software engineering tasks.
These works do not imply that adding agents automatically improves a system. Naive agent chains can multiply inconsistency and hallucination. AgentWeave's contribution is therefore the runtime around collaboration: durable messages, explicit task ownership, observable state transitions, evidence, recovery, and human approval.
References:
- AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation
- CAMEL: Communicative Agents for “Mind” Exploration of Large Language Model Society
- Improving Factuality and Reasoning in Language Models through Multiagent Debate
- MetaGPT: Meta Programming for A Multi-Agent Collaborative Framework
The core loop is:
goal → decompose → assign or parallelize → execute → communicate → review
→ attach evidence → recover or continue → request human approval
This makes long-running work visible: humans can see what each agent is doing, which task is moving, what messages caused a handoff, and why the system is waiting.
The two diagrams below deliberately separate the current, code-backed
runtime from the agent-owned collaboration vision. Solid components and
arrows in the first diagram describe behavior implemented on main. Dashed
components and arrows in the second are planned work, not product claims.
flowchart TB
Human[Human operator] <--> Dashboard[React Dashboard<br/>operator console]
subgraph Control[Control Plane — current implementation]
API[Control API<br/>HTTP · WebSocket · lifecycle]
Orch[Lifecycle & legacy orchestrator<br/>routing · state transitions · recovery]
Gate[Structured Result Gate<br/>validate agent result · resolve roles · apply approval rules]
Projection[Snapshot & runtime projection<br/>durable state + live events]
end
subgraph Durable[Durable Backbone — current implementation]
DB[(PostgreSQL — source of truth<br/>tasks · insights · messages · evidence · sessions · receipts)]
NATS[(NATS JetStream — durable transport<br/>inboxes · commands · execution events)]
end
subgraph Runtime[Execution Plane — one or more Worker processes]
Worker[Worker Runtime Pool]
Actor[Dynamic AgentRuntime<br/>one serialized inbox per agent identity]
Session[Durable provider session<br/>checkpoint · resume · cancellation]
Adapter[Provider adapter<br/>Mock · Codex App Server · Claude Code · Kiro · Ollama]
Workspace[Workspace & evidence boundary<br/>tests · diffs · artifacts]
Worker --> Actor --> Session --> Adapter
Actor --> Workspace
end
Dashboard <--> API
API --> Orch
API --> Projection
API <--> DB
Orch --> DB
Orch --> NATS
NATS -->|worker result events| Gate
Gate -->|atomic task · insight · inbox-message effects| DB
Gate -->|recipient inbox delivery after commit| NATS
NATS --> Worker
Worker -->|normalized execution events| NATS
DB --> Projection
PostgreSQL is the source of truth. The Control API writes durable state and
then publishes inboxes/events through JetStream; a crash-atomic transactional
outbox is not implemented yet.
Parts of this diagram are implemented today: agents submit structured decisions (proposals, critiques, synthesis, task decomposition, completion proposals) that the Control API validates before any effect is committed. Context packs, agent memory, and compaction remain planned. The implemented Control API, PostgreSQL, and JetStream boundary remains the validation and durability point even as agents become more self-directed.
flowchart TB
Human[Human operator] <--> Dashboard[React Dashboard]
subgraph CurrentBoundary[Current durable boundary — implemented]
Gate[Control API<br/>validation · policy · durable commit]
DB[(PostgreSQL<br/>source of truth)]
NATS[(NATS JetStream<br/>durable inbox transport)]
Gate <--> DB
Gate --> NATS
end
subgraph PlannedRuntime[Planned: agent-owned collaboration runtime]
Inbox[Read durable Inbox]
Context[Build Context Pack<br/>task · evidence · session summary · memory]
Loop[Plan → Act → Observe]
Tools[Provider & tools]
Result[Structured result<br/>insight · task · message · decision]
Memory[Memory, summaries & compaction]
Inbox -.-> Context -.-> Loop -.-> Tools -.-> Result
Loop -.-> Memory
Memory -.-> Context
end
subgraph PlannedHive[Planned: multiple dynamic agent identities]
PM[PM]
PE[PE]
Coder["Coder(s)"]
QA[QA]
PM <-. structured messages / shared insights .-> PE
PM <-.-> Coder
PE <-.-> QA
Coder <-.-> QA
end
Dashboard <--> Gate
NATS -. planned autonomous inbox consumption .-> Inbox
Result -. validated before effects .-> Gate
Loop -. one loop per identity .-> PM
Loop -.-> PE
Loop -.-> Coder
Loop -.-> QA
The Control API is the provider-neutral coordination boundary. It exposes HTTP and WebSocket APIs for the dashboard, owns workstream lifecycle commands, creates and updates tasks, applies policy and approval rules, and runs the Orchestrator state machine.
The Orchestrator handles routing, state transitions, retries, recovery, and human escalation. It can coordinate sequential work as well as independent or parallel tasks; a task does not have to be a strict child of another task.
PostgreSQL is the source of truth for workstreams, agents, tasks, messages, inboxes, sessions, leases, and evidence. NATS JetStream transports commands and events between the Control Plane and workers with durable consumers, acknowledgements, retries, and dead-letter handling.
The dashboard is a read-oriented operator console. Its task board, agent execution cards, live message bus, summaries, and activity views are projected from durable state and live events, so a refresh does not erase the history.
Workers register, send heartbeats, acquire task leases, consume agent inboxes, run provider sessions, and publish normalized execution events. Each runtime actor has its own role, status, current task, session, usage, and auditable output.
The provider adapter boundary supports Mock, Codex App Server, Claude Code, Kiro, Ollama, and future providers behind one contract for streaming, cancellation, resume, failure classification, checkpoints, and usage. Provider-reported token usage is forwarded from the app server's usage notifications through the worker into durable events, and the dashboard aggregates it per agent in Session Totals — the numbers are the provider's own accounting, not estimates. Workspace access is explicit and bounded; tests, diffs, tool output, and artifacts are persisted as evidence instead of remaining hidden in a transcript.
The renderable sources are architecture.mmd (current) and
architecture-vision.mmd (planned vision).
- Workstream — a durable long-running objective and its lifecycle.
- Task — an actionable unit with an owner, acceptance criteria, dependencies, relationships, status, and evidence. Tasks may be sequential, parallel, or independent.
- Agent actor — a runtime identity such as PM, PE, Coder, or QA. A role is an execution responsibility, not a separate product.
- Message bus — durable human ↔ agent and agent ↔ agent communication with correlation and causation IDs.
- Session — provider-specific state that can be leased, checkpointed, resumed, cancelled, and safely retried.
- Human boundary — explicit pause, resume, approval, rejection, and escalation points. Autonomy remains legible and controllable.
- TypeScript monorepo managed by pnpm and Turborepo
- React 19, Mantine, and React Flow for the operator dashboard
- Fastify for the Control API
- PostgreSQL for durable state and session recovery
- NATS JetStream for commands, events, inboxes, ACKs, retries, and DLQ flows
- Docker Compose for the local runtime
- Vitest, Playwright, and TypeScript checks for validation
- Prometheus, Loki, Promtail, and Grafana for local observability
AgentWeave is a developer preview. The table below separates behavior that is
available on main from work that is intentionally still in progress.
| Capability | Status | Current boundary |
|---|---|---|
| Durable Workstreams, Tasks, Messages, evidence, and provider sessions in PostgreSQL | Implemented | Designed for the trusted, single-host Docker deployment |
| Per-Workstream event sequence, reconnect cursor, and persisted Dashboard projections | Implemented | Replays committed history; full crash-atomic publication is not yet guaranteed |
| Deterministic Mock-provider operator journey | Implemented | Playwright covers create, start, activity, Human approval, and persisted completion |
| Mock, Codex App Server, Claude Code, Kiro, and Ollama provider adapters | Implemented | Codex App Server is the primary real-provider path (stdio or host bridge); Kiro drives the Kiro CLI headlessly with a tolerant JSONL parser and hermetic stub-CLI tests (no real install in CI); Ollama runs local models through the same adapter contract; Mock remains the deterministic path for CI and demos |
| Per-role provider/model routing within one workstream | Implemented | roleProviders overrides are resolved by recipient role in the Control API, stamped on every turn, and selected lazily by the Worker; unconfigured roles inherit the workstream route or Worker environment default |
| Provider token-usage accounting | Implemented | Per-agent usage from the provider's own usage notifications, aggregated into dashboard Session Totals; never estimated |
| Dashboard human gates and mid-run steering | Implemented | Gates pause the workstream for approve-and-continue, approve-and-complete, or reject; steering is delivered to agent inboxes and answered in the open event stream |
| Durable agent inboxes and structured Human ↔ Agent / Agent ↔ Agent messages | Partial | Transport and contracts exist; agent-owned collaboration policy is still evolving |
| Insight and collaboration-round contracts, persistence, and read projections | Implemented | Automatic proposal, critique, and synthesis rounds run against real providers; decomposition is submitted as a validated structured decision, not parsed from prose |
| Worker heartbeats, task leases, retries, and dead-letter handling | Partial | Basic runtime signals exist; dependency-aware scheduling and cross-Worker lease recovery are planned |
| Transactional state change + event outbox | Planned | A crash between database commit and event publication can still require operator diagnosis |
| Production security and untrusted multi-tenancy | Not supported | No built-in authentication/authorization boundary; deploy only on a trusted local network |
“Implemented” describes code exercised on main; it is not a production
support guarantee. See the open v0.2 roadmap
for the remaining reliability and collaboration work.
Workers forward validated AgentTurnResult values to the Control API. An agent
can propose insights, assign tasks, and address another role directly; the
runtime resolves role names and turn-local IDs rather than trusting model-supplied
agent or workstream identities. Insight references must resolve within the same
workstream, and cited evidence must belong to the executing task.
To dispatch a newly proposed task, include a message whose taskId matches that
task's local id and whose recipientRole matches its ownerRole. Creating a task
alone does not schedule it. Results may also request Human input or propose
completion; neither bypasses Human approval. Summary-only results retain the
legacy orchestration path, while malformed declared JSON is rejected.
Tasks, insights, durable inbox messages, source-task status, and a retry receipt are committed in one PostgreSQL transaction. Reapplying the same turn does not duplicate these records, and conflicting reuse of a turn ID is rejected. NATS publication follows that transaction: this is not a crash-atomic outbox or a complete autonomous collaboration policy yet. The deterministic Mock demo exercises a structured PM → PE → Backend → QA → PM handoff and persists a proposal.
CI runs PostgreSQL-backed retry/rollback tests and a Playwright journey that
verifies the proposal remains after reload. Run the database checks against a
disposable database with STRUCTURED_TURN_TEST_DATABASE_URL set and
pnpm --filter @agentweave/control-api exec vitest run tests/structured-turn-postgres.test.ts.
- Create a workstream from a one-sentence goal in the dashboard.
- Run a collaboration round: independent proposals, critique, and synthesis.
- Decompose the synthesized plan into tasks through a validated structured decision, then execute tasks in parallel across role agents (PM, PE, Backend, Frontend, QA, DevOps).
- Route typed human and agent messages through NATS JetStream; persist workstream state and read models in PostgreSQL.
- Watch everything in the React dashboard: task board, agent cards, live event stream, human gates, steering, and per-agent token totals.
- Close the workstream only after validation evidence and human approval.
apps/control-api HTTP/WebSocket control plane
apps/dashboard React operator console
apps/worker Local multi-role worker runtime
packages/protocol Provider-neutral event and command schemas
packages/domain Workstream state machine and domain rules
docs Product specification and implementation backlog
AgentWeave is an orchestrator, not a model host: providers run the models, so no GPU is required and the runtime itself is light. On the current deployment host, the full stack (Control API, worker with a resident Codex app server, PostgreSQL, NATS) uses roughly 1.5 GB of RAM in total; the real load during a run is concurrent provider sessions plus whatever builds and test suites the agents execute inside workspaces.
| Tier | CPU | RAM | Disk | Notes |
|---|---|---|---|---|
| Minimum — mock demo and light use | 2 vCPU | 4 GB | 10 GB | The credential-free demo path. The core services alone have also run on a 1 GB micro instance. |
| Recommended — real-provider agent runs | 4+ vCPU | 8+ GB | 20+ GB | Headroom for several concurrent Codex sessions and in-workspace builds/tests. Verified end to end on an 8 OCPU / 48 GB host, with total memory use staying in the single-digit GB range. |
Software:
- Linux host (Ubuntu 22.04 verified) with Docker and Docker Compose for the standard deployment, or Node.js 22+ with pnpm 11.2.2 for development.
- For real-provider runs: the Codex CLI with an authenticated subscription or API credentials on the worker host (or reachable through the host bridge), plus outbound HTTPS to the provider.
- Local ports 3000 (Control API) and 5173 (Dashboard); keep PostgreSQL, NATS, and the Codex bridge off public networks (see SECURITY.md).
The default provider is deterministic mock, so anyone with Docker can see a
workstream run without provider credentials or access to a real repository.
corepack enable
pnpm install
cp .env.example .env
make demoOpen the Dashboard at http://localhost:5173 and select the created demo
workstream from the Workstreams menu. make demo is safe to run again: it
creates another disposable demo workstream; it never deletes existing work.
You can also create the demo directly in the Dashboard from New Workstream by choosing Create demo workstream. The mock demo visibly moves through PM → PE → Coder → QA and then stops at Human review, with no provider credentials or real project workspace required.
Dashboard: http://localhost:5173 Control API: http://localhost:3000/health NATS monitoring: http://localhost:8222
For a prerequisite check, run make doctor. For the full development and
configuration guide, see docs/DEVELOPMENT.md and
docs/CONFIGURATION.md.
To remove only your local Docker state and begin from an empty database, run
make fresh CONFIRM=YES. This intentionally deletes local database, NATS, and
observability volumes; it does not delete the mounted workspace directory.
Codex is an opt-in local preview, not required for the quick start. When the
worker itself runs on a host with Codex installed, no bridge is needed: the
worker spawns codex app-server directly over stdio. Otherwise the bridge
executes Codex on your host while the Worker stays in Docker.
- Set
AGENTWEAVE_PROVIDER=codexin.env. - Set both
AGENTWEAVE_HOST_WORKSPACEandCODEX_HOST_WORKSPACE_ROOTto the same narrow directory that you explicitly allow AgentWeave to access. - Generate a private
CODEX_BRIDGE_TOKENand place it only in.env. - Start the bridge in a separate terminal with
make bridge, then runmake demo-codexin another terminal. This is the one-command way to start the stack with the real Codex provider and create a demo workstream. To start the Codex-backed stack without creating a demo, runmake upinstead.
To verify the authenticated provider boundary without changing files, run the documented read-only smoke turn from another terminal:
CODEX_SMOKE_WORKSPACE=/absolute/path/inside/the/allowed/root pnpm test:smoke:codexmake bridge loads .env before starting, so the host bridge uses the same
workspace mapping as Docker.
The bridge defaults to localhost when no token is set. Do not mount a home directory, expose the bridge publicly, or put provider credentials in task messages, logs, screenshots, or Git.
AgentWeave is pre-1.0 / developer preview. It is intended for trusted, single-host experimentation. It is not production-hardened or suitable for untrusted multi-tenant deployment.
Before tagging or publishing a developer-preview build:
- Start from a clean clone with Node.js 22+, pnpm 11.2.2, and a running Docker daemon.
- Run
cp .env.example .env,corepack enable,pnpm install, andmake demo; confirm the Dashboard reaches Human review without manual database changes. - Run
pnpm run typecheck,pnpm run test, andpnpm run build. - Run the deterministic browser journey with
pnpm test:e2e; it must not require provider credentials or paid tokens. - Confirm the repository's
CI workflow
passes its
quality,docker, ande2ejobs for the release commit. - Review SECURITY.md, keep PostgreSQL, NATS, observability, and the Codex bridge private, and verify no credential or broad host workspace mount is included.
- Record known limitations from the capability matrix in the release notes; do not claim transactional crash recovery, untrusted multi-tenancy, or autonomous collaboration until their roadmap issues are complete.
AgentWeave is released under the Apache License 2.0.