duoduo
A model call ends. The work shouldn't.
DuoDuo is a long-lived local runtime for Claude, Codex, Grok, and Pi. Conversations, jobs, outputs, and prompts live in files on your machine. Foreground sessions handle live work; a scheduled subconscious distills experience into an intuition layer that every new session starts with, kept in Git so every change to what DuoDuo has learned has a diff and a revert.
DuoDuo is not another harness. Claude, Codex, Grok, and Pi are the harnesses, and they keep improving; DuoDuo is the environment that gives them durable state, time, channels, and a Git-tracked history. Talk to it from any channel you plug in: a chat app, a room, a button in your pocket, or another assistant that becomes DuoDuo through Tether.
Site and documentation: openduo.ai.
Why Not Open Source?
First: we are called openduo and we don't publish source either. Respect to OpenAI.
The real reason: this codebase is not written for humans to read.
duoduo is an agent that codes itself. The published npm packages contain minified JavaScript. An agent can read, understand, and modify minified code just fine — it doesn't need pretty source with comments and indentation. Minification here isn't obfuscation; it's compression. Saves bandwidth. Keeps the context window lean.
Humans don't need to read the source. Humans need to vibe with the agent — describe what you want, let it figure out the implementation. That's the whole point.
Human? Read this README, then run it and talk to it.
Agent? The minified bundle is your source. See Issues.
What you may do with it
Source-available, and open to your agents. The bundle is licensed to you and to the agents you run: read it, de-minify it, debug it, patch it, train on it, and share your patches. The one thing you may not do is offer it, or something built from it, as a competing product or service. Two years after each release, that version becomes Apache-2.0. The terms are in LICENSE; the summary an agent can act on is LICENSE.agents.yaml.
Core Innovations
1. Filesystem-First, Event-Sourced Runtime
All state — conversations, outputs, jobs, memory — lives in durable files. Nothing critical is held in process memory. The canonical event log (WAL) is written before any action executes. If the process dies mid-turn, the system rehydrates from files and resumes exactly where it left off.
This is not a backup strategy. The filesystem is the database. The event log is the source of truth. The process is stateless by default.
2. WAL-Before-Execute at the Gateway Boundary
Every inbound message follows a strict contract: write a canonical event to the append-only log first, then enqueue the session, then execute. Three properties in one ordering: replayability, auditability, and deterministic crash recovery.
3. One External Identity, Many Internal Sessions
Externally, duoduo presents one coherent agent identity. Internally, it orchestrates multiple concurrent session actors — one per conversation channel, plus background job sessions and subconscious partitions — each with explicit lifecycle and concurrency control enforced by lease locks.
4. Dual-Loop Cognition: Cortex + Subconscious
Foreground (Cortex) responds to live channel messages. Sessions persist across restarts and resume conversation history exactly.
Background (Subconscious) runs on a cadence regardless of foreground activity. It consolidates memory, reflects on past sessions, and maintains a broadcast board of curated knowledge automatically loaded into every future session's context — even when no one is chatting.
5. Self-Programming Cognitive Topology
Subconscious behavior is defined by filesystem files — each partition has its own prompt, schedule, and cooldown. Partitions can modify their own prompts, create new partitions, and adjust their execution schedule. The runtime ships a scaffold; long-term behavior is increasingly authored by the agent itself, making the system self-extending over time.
6. Minimal Runtime Layer, Maximum Model Delegation
duoduo keeps application code deliberately thin. Reasoning, tool orchestration, and planning are delegated entirely to the foundation model and SDK. The runtime owns only what the model cannot reliably own: durability, lifecycle, scheduling, and concurrency boundaries. As the model improves, the system improves without code changes.
Dashboard
duoduo includes a built-in ATC (Air Traffic Control) monitoring panel. Access it at http://localhost:20233/dashboard while the daemon is running.
A single-file, zero-dependency HTML page served directly by the daemon. No build step, no extra port, no framework.
Header — cumulative cost, token usage, tool call count, and system health indicator.
Signal Bar — compact status indicators for every active entity in the runtime:
| Shape | Meaning |
|---|
| ● Circle | Foreground session (Cortex) — live channel connections (Feishu, ACP, stdio) |
| ■ Square | Cron job (Rhythm) — periodic scheduled tasks |
| ◆ Diamond | One-shot job — spawned tasks that run once |
| ✓ / · | Subconscious partition — background cognitive partitions |
| Color | Meaning |
|---|
| Green | Actively executing right now |
| Blue | Standby — idle or last run succeeded |
| Red | Alert — error or last run failed |
| Gray | Ended or never run |
Indicators blink when new events arrive for their entity. Hover for details (session key, job schedule, run count, last activity).
This is the beginning of the README. Read the rest at the original. Read the full README ↗
