duhwave

What is duhwave

A single-agent harness is one loop: one prompt, one model, one tool registry. It exits when the work is done. duhwave keeps the loop alive past any single CLI invocation, accepts work from external triggers (webhooks, file watches, cron, MCP push), and lets a coordinator delegate to specialised workers via a shared substrate of variable handles instead of prose summaries.

The architecture composes from six primitives: an RLM substrate (one Python REPL subprocess per session, large inputs bound as named variables), a persistent Task lifecycle (forward-only state machine, three execution surfaces, JSONL on disk), a coordinator-as-prompt-role (one engine, no subclasses, tool filtering by allowlist), recursive cross-agent links (workers see scoped handles, results bind back as new handles), an event-ingress layer (five listeners, one immutable Trigger type, one append-only TriggerLog), and a topology DSL (one TOML file, packed and signed as a .duhwave bundle).

Five ADRs

duhwave's design lives in five Architecture Decision Records. Each ADR ships with implementation under duh/duhwave/, unit and integration tests under tests/, and at least one runnable demo under examples/duhwave/.

Quick start

Install D.U.H., write a minimal swarm.toml, install the bundle, start the host daemon. The daemon stays alive until you stop it; triggers spawn Tasks; Tasks run agents; agents bind results back as REPL handles.

# 1. Install D.U.H. (duhwave ships in the same package)
pip install duh-cli

# 2. Author a topology directory: foo.duhwave/{manifest.toml, swarm.toml, permissions.toml}
#    See examples/duhwave/repo_triage/ for the canonical layout.

# 3. Install the bundle into ~/.duh/waves/
duh wave install ./foo.duhwave

# 4. Start the host daemon
duh wave start

# 5. Inspect what is running
duh wave ls
duh wave inspect foo
duh wave logs --follow foo

# 6. Stop the daemon when done
duh wave stop

A minimal swarm.toml:

[swarm]
name           = "hello-wave"
version        = "0.1.0"
format_version = 1

[[agents]]
id            = "coordinator"
role          = "coordinator"
model         = "anthropic/claude-haiku-4-5"
tools         = ["Spawn", "SendMessage", "Stop", "Peek", "Search", "Slice"]
system_prompt = "prompts/coordinator.md"

[[agents]]
id            = "worker"
role          = "worker"
model         = "anthropic/claude-haiku-4-5"
tools         = ["Read", "Grep", "Peek", "Search", "Slice"]
system_prompt = "prompts/worker.md"

[[triggers]]
kind            = "manual"
source          = "hello"
target_agent_id = "coordinator"

[[edges]]
from_agent_id = "coordinator"
to_agent_id   = "worker"
kind          = "spawn"

[budget]
max_concurrent_tasks = 3
max_usd_per_day      = 1.00

10 runnable demos

Every duhwave primitive is exercised by a runnable demo under examples/duhwave/. The parity_hermes/ set walks through five harness-parity demos; parity_claw/ walks through four control-plane demos. The headline showpieces — repo_triage/, agile_team/, real_e2e/, telegram_assistant/ — are full end-to-end swarms.

Real-OpenAI benchmark

A single CLI invocation drives a 5-stage agile-team pipeline (PM → Architect → Engineer → Tester → Reviewer) against real OpenAI models. Each stage spawns a worker, reads exposed handles from the coordinator's RLM REPL, and binds its result back. The benchmark runs pytest against the produced implementation; the pass rate is the headline number.

Headline finding. Real coordination defects surface naturally — the Reviewer agent reads but does not execute, missing test failures the Tester introduced. gpt-4o-mini's test_error_handling fails because an earlier time.sleep(2) refills the bucket; gpt-4o's test_rate_limiter_thread_safety references threading.Thread but the test file imports only pytest and time. Both Reviewers issued APPROVE. The obvious next step: add a Runner role that executes the test suite and binds the failures back as a handle for the Reviewer to peek. Architecture composes.

Full write-up with per-stage ledger, cost breakdown, and reproducibility steps: benchmarks/duhwave-agile/RESULT.md.

Architecture

duhwave's five ADRs form a dependency DAG. ADR-028 (RLM substrate) is the foundation; everything else builds upward.

                  ┌──────────────────────────────────────┐
                  │          ADR-032 — topology          │
                  │   swarm.toml · .duhwave bundles ·    │
                  │      duh wave CLI control plane       │
                  └─────────────┬────────────────────────┘
                                │ declares
                  ┌─────────────▼────────────────────────┐
                  │     ADR-031 — coordinator + ingress   │
                  │  Role / tool filtering · 5 listeners ·│
                  │     SubscriptionMatcher · TriggerLog  │
                  └──────┬────────────────────────┬──────┘
                         │ spawns                 │ persists
              ┌──────────▼─────────┐   ┌──────────▼──────────┐
              │ ADR-029 — Spawn   │   │ ADR-030 — Task       │
              │ cross-agent       │   │ state machine       │
              │ handle exposure ──┼──▶│ 3 execution surfaces │
              │ + bind-back        │   │ JSONL persistence   │
              └─────────┬──────────┘   └──────────┬──────────┘
                        │                          │
                        │  both stand on           │
                        ▼                          ▼
                  ┌──────────────────────────────────────┐
                  │     ADR-028 — RLM context engine      │
                  │   one Python REPL subprocess per     │
                  │   session · handles · Peek / Search  │
                  │   / Slice · cycle-detected recursion  │
                  └──────────────────────────────────────┘

See also

• Cookbook — build your own swarm on D.U.H. · the canonical walkthrough
• All ADRs on GitHub · ADR-028 through ADR-032 cover duhwave
• examples/duhwave/ · 10 runnable demos
• benchmarks/duhwave-agile/RESULT.md · real-OpenAI agile-team benchmark
• Zhang, Kraska, Khattab — Recursive Language Models (arXiv 2512.24601)
• Yang, Zou, Pan et al. — Recursive Multi-Agent Systems (arXiv 2604.25917)
• github.com/nikhilvallishayee/duh · D.U.H. repo