Skip to content

About

Open-source runtime OS for collaborative AI agents.

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

Latest commit

 

History

355 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AgentWeave

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:

  1. Propose — agents independently draft competing solutions, no groupthink.
  2. Critique — a reviewer agent challenges every proposal and finds the holes.
  3. Rebut — proposers defend their ideas and address the criticism.
  4. Synthesize — a lead agent combines the best of all sides into one decision.
  5. 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.

Who it is for

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.

Differentiators

Dynamic collaboration

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.

Human-in-the-loop accountability

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.

Heterogeneous model orchestration

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.

Durable, recoverable execution

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).

Adaptive collaboration (direction)

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.

Research context and design thesis

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:

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.

Architecture

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.

Current runtime architecture

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
Loading

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.

Agent-owned collaboration vision — partially implemented

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
Loading

Control Plane

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.

Durable Backbone

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.

Execution Plane

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).

Runtime concepts

  • 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.

Technology stack

  • 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

Capability matrix

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.

Structured agent results

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.

Current scope

  • 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.

Repository layout

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

System requirements

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).

Quick start: reliable local demo

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 demo

Open 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.

Run with Codex

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.

  1. Set AGENTWEAVE_PROVIDER=codex in .env.
  2. Set both AGENTWEAVE_HOST_WORKSPACE and CODEX_HOST_WORKSPACE_ROOT to the same narrow directory that you explicitly allow AgentWeave to access.
  3. Generate a private CODEX_BRIDGE_TOKEN and place it only in .env.
  4. Start the bridge in a separate terminal with make bridge, then run make demo-codex in 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, run make up instead.

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:codex

make 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.

Release status

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.

Developer-preview release checklist

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, and make demo; confirm the Dashboard reaches Human review without manual database changes.
  • Run pnpm run typecheck, pnpm run test, and pnpm 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, and e2e jobs 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.

Community and security

AgentWeave is released under the Apache License 2.0.

About

Open-source runtime OS for collaborative AI agents.

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages