Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/zhixuli0406/duduclaw

Open-source AI Agent platform β€” 80+ MCP tools, 7 channels (Slack/Discord/LINE/Telegram), Rust + Python. Self-hostable Claude/GPT alternative for production multi-LLM systems.
https://github.com/zhixuli0406/duduclaw

agent-platform agentic-ai ai-agent claude gemini llm llm-agent mcp mcp-server model-context-protocol multi-llm openai python rag rust taiwan-oss

Last synced: 3 days ago
JSON representation

Open-source AI Agent platform β€” 80+ MCP tools, 7 channels (Slack/Discord/LINE/Telegram), Rust + Python. Self-hostable Claude/GPT alternative for production multi-LLM systems.

Awesome Lists containing this project

README 

          
# DuDuClaw 🐾






[繁體中文](README.md) Β· **English** Β· [ζ—₯本θͺž](README.ja.md)






> **Multi-Runtime AI Agent Platform** β€” unifying the three major CLIs (Claude / Codex / Gemini) to build your multi-channel AI assistant



[![CI](https://github.com/zhixuli0406/DuDuClaw/actions/workflows/ci.yml/badge.svg)](https://github.com/zhixuli0406/DuDuClaw/actions/workflows/ci.yml)

[![Rust](https://img.shields.io/badge/Rust-2024_edition-orange?logo=rust)](https://www.rust-lang.org/)

[![Python](https://img.shields.io/badge/Python-3.9+-blue?logo=python)](https://www.python.org/)

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)

[![Version](https://img.shields.io/badge/version-1.30.1-blue)](https://github.com/zhixuli0406/DuDuClaw/releases)

[![npm](https://img.shields.io/npm/v/duduclaw?logo=npm)](https://www.npmjs.com/package/duduclaw)

[![PyPI](https://img.shields.io/pypi/v/duduclaw?logo=pypi)](https://pypi.org/project/duduclaw/)



---



## πŸ”’ Trust & Security



This is an open-source project β€” here's full transparency on what you're installing.



### Why is a "new" npm package already at version 1.21+?



DuDuClaw had several months of intensive development in a private repository (400+ commits) before

going public. See the [git log](https://github.com/zhixuli0406/DuDuClaw/commits/main) for full history.



### What's inside the npm package?



- A small JS wrapper that only invokes the platform-specific Rust binary

- The platform binary ships via npm `optionalDependencies` (`@duduclaw/`) β€”

  **no postinstall script downloads and executes external code from arbitrary URLs**

- `postinstall` only checks that the platform package is present (see

  [`npm/duduclaw/scripts/install.js`](npm/duduclaw/scripts/install.js)) β€” it downloads and executes nothing

- GitHub Release binaries ship with SHA-256 checksums



### Building from source (if you don't trust the prebuilt binary)



```bash

git clone https://github.com/zhixuli0406/DuDuClaw

cd DuDuClaw

cargo build --release

```



### Binary verification



Every release ships with SHA-256 checksums and a keyless [cosign](https://github.com/sigstore/cosign) signature:



```bash

# Download from Releases

wget https://github.com/zhixuli0406/DuDuClaw/releases/download/v1.21.1/duduclaw-darwin-arm64.tar.gz



# Verify SHA-256 (against the .sha256 file in the release)

shasum -a 256 -c duduclaw-darwin-arm64.tar.gz.sha256



# Verify the cosign signature

cosign verify-blob \

  --certificate duduclaw-darwin-arm64.tar.gz.pem \

  --signature duduclaw-darwin-arm64.tar.gz.sig \

  --certificate-identity-regexp "https://github.com/zhixuli0406/DuDuClaw" \

  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \

  duduclaw-darwin-arm64.tar.gz

```



### Supply chain transparency



- **License**: Apache 2.0

- **Maintainer**: ε˜Ÿε˜Ÿζ•Έδ½η§‘ζŠ€ζœ‰ι™ε…¬εΈ (Taiwan-registered company, η΅±η·¨ 94139082)

- **Public commit history**: github.com/zhixuli0406/DuDuClaw

- **CI/CD**: All releases are built via GitHub Actions

- **No telemetry**: zero phone-home calls

- **No API key collection**: all secrets stay on your machine via an AES-256-GCM vault

- **No privileged escalation**: runs entirely in user space



To report a vulnerability, see [SECURITY.md](SECURITY.md).



---



## Why DuDuClaw vs Using Native Claude / GPT / Gemini CLIs?



The native CLIs are great if you're using one LLM occasionally as a person.

But once you need to ship to production, you'll quickly end up rebuilding what DuDuClaw already

provides:



| Need | Native CLIs | DuDuClaw |

|---|---|---|

| Multi-LLM auto-fallback | Manual restart | Built-in (4 strategies) |

| Context preserved across LLM switches | Lost | Preserved |

| Tools shared across LLMs | Rewrite per LLM | Write once, share |

| Production hardening (DLQ/retry/observability) | Build yourself | Built-in |

| Multi-channel (Telegram/LINE/Discord/...) | CLI only | 7 channels |

| Secrets / audit / PII redaction | Build yourself | Built-in |



If you're solo using `claude` or `gemini` occasionally β€” stick with native.

If you're building **production multi-LLM Agent systems** β€” DuDuClaw saves you 3 months of

infrastructure work.



---



> πŸŽ‰ **v1.29.0 β€” Cloud-tier agent/channel caps (self-host never limited)** ([Release](https://github.com/zhixuli0406/DuDuClaw/releases/tag/v1.29.0))

>

> Enforces the per-tier `max_agents` / `max_channels` from `features.toml` that were declared but never applied (Hobby 1 agent/1 channel, Solo 1/2, Studio 3/5). **Self-host is never capped** (Apache 2.0 promise); the limit only applies to managed Cloud tenants.

>

> - **Cloud-tier resource caps** β€” `agents.create` / `channels.add` reject once the active tier's cap is reached, with an upgrade message. Gated on `DUDUCLAW_DEPLOYMENT=cloud` (set only inside managed tenant containers); self-host (default) is never limited, and `max_* = 0` also means unlimited

> - **Soft-limit banner** now shows concrete usage (`Agents X/Y Β· Channels A/B`) + an upgrade CTA when a personal cloud tenant reaches its plan limit β€” non-blocking, dismissible

> - `license_runtime::cap_exceeded()` pure helper + `is_self_host_deployment()` exposed to the gateway



https://github.com/user-attachments/assets/217f56aa-8b46-4c2a-85fa-62ee68c33a4c



v1.9.4 β†’ v1.28.x cumulative highlights



- **v1.28.0** β€” Partner (NFR) licenses + license self-service: a free, non-resellable Partner tier (unlocks Self-Host Pro modules) + self-serve partner-code redemption (`POST /v1/partner/redeem`) + CLI `redeem/rebind/subscriptions` + emailed key on issuance + machine rebind + deployment-mode binding (M51, `DUDUCLAW_DEPLOYMENT` cloud/self-host, fail-closed)

- **v1.27.0** β€” Premium industry templates (`ecommerce` / `clinic` / `realestate` / `education`, each a full closed-source kit with cited Taiwan statutes) + license-gated `premium_templates` unlock (fail-closed; the public OSS binary never receives the closed content) + wizard premium-industry menu with upsell hint

- **v1.26.0** β€” Personal / Enterprise editions (`EditionProfile`, orthogonal to the license tier, never gates core features) + Dashboard one-click CLI login (PTY-driven native login for Claude/Codex/Gemini/Antigravity with paste-back + `remote_safe` classification) + Antigravity CLI bundled in the server image + personal-edition data portability (`export`/`import`) + `PersonalProSelfHost` self-host license tier (NT$490/mo)

- **v1.25.0** β€” Browser-first onboarding: `WelcomePage` (3 steps, 5 AI-backend paths) + `FirstRunGate` zero-agent routing + guided product tour `GuidedTour` (zero-dep spotlight) + `runtime.detect` RPC zero-config boot

- **v1.24.0** β€” Antigravity CLI (`agy`) runtime Β· PtyPool unbound from Claude: adds `RuntimeType::Antigravity` (oneshot `agy -p`, binary auto-resolve, system prompt + history embedded, CJK-safe truncation, pre-seeded `trustedWorkspaces`); `CliKind::Antigravity` wired into PtyPool / worker spawn, `cli_kind_for_provider()` derives the kind from `[runtime] provider`; interactive REPL stays Claude-only (by design); the legacy `gemini` backend is retained for paid `GEMINI_API_KEY` / enterprise

- **v1.23.0** β€” Decision Continuity (RFC-24): when an agent offers the user an enumerated choice (Option A/B/C), each option is persisted into the Temporal Memory **semantic** layer (independent of conversation compression) and open decisions are re-injected each turn; a later "use Option C" (new turn / session / process) resolves from durable state instead of being guessed. Detection is deterministic and zero-LLM; opt-in per agent via `[memory] decision_continuity = true`

- **v1.22.0** β€” RFC-26 Live Forking (rounds 1–4): split an in-flight task into N competing branches that explore different strategies in copy-on-write isolated workspaces and let an AI judge pick the winner (`duduclaw-fork` + 6 MCP tools + cross-process `ForkStore` + `RotatingBranchExecutor` + `LiveAggregate` budget pre-emption); the Skill-synthesis scheduler (W19-P1); and the Calm Glass dashboard rebuilt on a shared component library. All off by default

- **v1.21.0** β€” RFC-25 Β§5 followups: the non-Claude (Codex / Gemini / OpenAI-compat) path closes all 11 gaps to become first-class (multi-turn context, cost telemetry, keepalive, per-(home,provider) failover backoff); `release.sh` multi-platform version sync + drift audit + post-bump assertion + `verify`, fixing the `skip-existing` silent PyPI freeze

- **v1.20.0** β€” RFC-25 Multi-Runtime Unlock + A2A: the "Multi-Runtime four-backend" abstraction was previously orphan, uncompiled source β€” every execution path hardcoded Claude. v1.20.0 wires it up and routes the LLM-calling subsystems through a single provider-agnostic choke-point (`runtime_dispatch::run_agent_prompt` + a lazily auto-detecting `RuntimeRegistry`); channel reply / GVU / sub-agent delegation route through the choke-point for non-Claude providers (Claude keeps its OAuth-rotation / PTY path, zero regression); ACP `tasks/send` actually runs the target agent and reports Failed / Completed; Phase 0 removed the GVU evolution-model hard-lock (reject β†’ warn)



- **v1.19.0** β€” Memory Intelligence: the W18/W19-designed memory layer, implemented non-invasively on the live Rust `SqliteMemoryEngine`. **Temporal Memory** (`memories` gains temporal / knowledge-graph columns + `store_temporal` automatic supersession chain + `get_history`/`get_at`; search default-filters to currently-valid memories); **Reflexion Loop** (bridges the existing `MistakeNotebook`: recall injected into the answering prompt + β‰₯3 same-category mistakes consolidated into a semantic rule); **`memory_fetch_batch`** MCP tool (fetch ≀100 entries by ID, namespace/ownership enforced). `MemoryEntry` unchanged, zero blast radius

- **v1.18.0** β€” Dashboard budget/usage correctness: reads from the persistent `CostTelemetry` ledger (replacing the in-memory counter that reset to zero on rebuild), fixes the `cost_millicents` unit misnomer, implements `marketplace.install`, fills settings-persistence gaps, plus a round of frontend runtime-bug cleanup + 88 i18n keys



- **v1.17.0** β€” RFC-24 License v2.0 (Open Core foundation): new crate `duduclaw-license` (verification-only client, signing keys stay in `commercial/duduclaw-license`), a 7-tier inheritance chain `OpenSource` / `Hobby` / `Solo` / `Studio` / `Business` / `SelfHostPro` / `Oem`, an Ed25519 trust registry seeded from `DUDUCLAW_LICENSE_PUBKEY_` env (empty registry fail-safe falls back to OpenSource). The Apache 2.0 core is **available without restriction**; paid subscriptions unlock the `commercial/*` value-add modules

- **v1.16.0** β€” MCP Refresh Tokens + GVU `SoulPatchOp::Consolidate`: new module `mcp_refresh` provides long-lived credentials backed by `~/.duduclaw/mcp_tokens.db` (`ddc_refresh__<64hex>`, 90 days, revocable, hash-only storage), solving the silent disconnect-without-retry after Claude Desktop auth-fail; GVU adds a `SoulPatchOp::Consolidate` variant carrying a "shrink invariant" so SOUL.md can self-trigger consolidation as it approaches the 150-line / 8KB hard cap

- **v1.15.2** β€” `agent_update_soul` trust-backdoor patch: previously writing SOUL.md did not call `soul_guard::accept_soul_change` to update the integrity hash, so every legitimate call left permanent stored-vs-current drift; and the entire call chain didn't write to `tool_calls.jsonl`, making the backdoor completely invisible to post-hoc analysis. v1.15.2 fills in the audit row (logging success + all four rejection paths, with a 16-char hash prefix) and syncs the fingerprint after every write

- **v1.15.1** — GVU SOUL.md unbounded-growth fix: agnes/SOUL.md bloated from 61 to 592 lines over 5 GVU cycles. Three layers of defense: (1) `strip_proposal_meta` strips meta sections like `## 診斷` / `## rationale` / `## expected_improvement` on the legacy path; (2) `SOUL_MAX_LINES = 150` / `SOUL_MAX_BYTES = 8KB` hard caps independent of the ASI content-weight threshold; (3) added a structured `SoulPatch { section, op, content }` and `apply_patch_to_soul`, wiring the full Generator→Verifier→Updater chain

- **v1.15.0** β€” Cross-Platform PTY Pool + Worker: Anthropic's official alternative path after it blocked `claude -p` for OAuth-subscription accounts. New crate `duduclaw-cli-runtime` (`portable-pty` ConPTY/openpty cross-platform + sentinel-framed in-band protocol + `PtyPool` semaphore + idle eviction + supervisor + restart policy) and `duduclaw-cli-worker` (localhost JSON-RPC + Bearer + `/healthz`, gateway can run it in-process or out-of-process); `channel_reply` routes OAuth via the REPL and API keys via `oneshot_pty_invoke + claude -p`; Phase 8 `pty_pool_*` Prometheus metrics; all failures fall back to legacy `tokio::process::Command`. Off by default; enable with `agent.toml [runtime] pty_pool_enabled = true`

- **v1.14.0** — RFC-23 Sensitive Data Redaction: new crate `duduclaw-redaction`. Internal data (Odoo / shared wiki / file tools) is replaced with `` tokens before being sent to the LLM, and automatically restored at trusted boundaries (user channel reply, whitelisted tool egress); AES-256-GCM encrypted SQLite vault (per-agent 32-byte key, 0o600 permissions) + a two-phase TTL 7d GC (mark→purge after 30 days) + 5 built-in profiles + a five-layer enable/disable resolver + JSONL audit with 10MB rotation

- **v1.13.1** β€” Odoo Test-Before-Save: the `odoo.test` RPC accepts inline params so the Dashboard "Test connection" button hits Odoo with the current form values without saving first; leaving the inline credential blank falls back to the stored key; the same SSRF / HTTPS / db-name validation chain applies, and `scrub_odoo_error()` truncates to 240 chars to prevent HTML error-page leakage

- **v1.13.0** β€” Runtime-health overhaul (16 issues / two rounds of fixes): restored GVU/SOUL self-evolution, added the `[prompt] mode = "minimal"` Anthropic Skills-style system prompt, the `[budget] max_input_tokens` compression pipeline, an async session summarizer, TF-IDF wiki relevance ranking, and the `duduclaw lifecycle flush` quarterly hot/cold-separation CLI

- **v1.12.x** β€” W22-P0 ADR-002 `x-duduclaw` capability negotiation (HTTP 422 early failure) + ADR-004 Secret Manager + RFC-22 multi-agent coordination fixes (agnes faking sub-agent responses / autopilot mass mis-triggering / channel-path token not logged) + the `duduclaw weekly-report` subcommand

- **v1.11.0** β€” RFC-21 ([Issue #21](https://github.com/zhixuli0406/DuDuClaw/issues/21)): `duduclaw-identity` crate (IdentityProvider trait + Wiki/Notion/Chained three implementations) + Odoo per-agent credential isolation (`OdooConnectorPool` replaces the global admin singleton) + shared wiki `.scope.toml` SoT namespace policy

- **v1.10.0** β€” Wiki RL Trust Feedback: `WikiTrustStore` per-agent SQLite trust, `CitationTracker` two-level LRU + bounded-time eviction to prevent DoS, `WikiJanitor` daily pass (auto-marking corrected / archive / frontmatter sync) + sub-agent turn_id propagation + multi-process flock + atomic batch upsert

- **v1.9.4** β€” `duduclaw-durability` five persistence mechanisms (idempotency / retry / circuit breaker / checkpoint / DLQ) + `duduclaw-governance` PolicyRegistry + MCP HTTP/SSE Transport + LOCOMO memory evaluation system (daily 03:00 UTC eval + 200 golden QA) + LLM Fallback + Discord RESUME + Web ReliabilityPage



---



## Table of Contents



- [What is DuDuClaw?](#what)

- [Core Features](#features)

- [Comparison](#comparison)

- [Agent Directory Structure](#directory)

- [Security Hooks](#security)

- [Installation](#install)

- [CLI Commands](#cli)

- [Project Structure](#structure)

- [Technical Decisions](#tech)

- [Testing](#testing)

- [Documentation](#docs)

- [License](#license)



---






## What is DuDuClaw?



DuDuClaw is a **Multi-Runtime AI Agent platform** β€” it supports the three major CLIs (**Claude Code / Codex / Gemini**) as AI backends simultaneously, with seamless switching and auto-detection via a unified `AgentRuntime` trait.



It is not tied to any single AI provider; instead, it gives your AI Agent the complete infrastructure of messaging channels, memory, self-evolution, local inference, and account management.



Core concepts:



- **Multi-Runtime** β€” the `AgentRuntime` trait unifies four backends (Claude / Codex / Gemini / OpenAI-compat), `RuntimeRegistry` auto-detects, and configuration is per-agent

- **Plumbing = DuDuClaw** β€” responsible for channel routing, session management, memory search, account rotation, local inference, and other infrastructure

- **Bridge = MCP Protocol** β€” `duduclaw mcp-server` acts as an MCP Server, exposing channel and memory tools to the AI Runtime



```

AI Runtime (brain) β€” Claude CLI / Codex CLI / Gemini CLI / OpenAI-compat

  ↕ MCP Protocol (JSON-RPC 2.0, stdin/stdout)

DuDuClaw (plumbing)

  β”œβ”€ Channel Router β€” Telegram / LINE / Discord / Slack / WhatsApp / Feishu / WebChat

  β”œβ”€ Multi-Runtime β€” Claude / Codex / Gemini / OpenAI-compat auto-detection + per-agent config

  β”œβ”€ Session Memory Stack β€” native --resume + Instruction Pinning + Snowball Recap + Key-Fact Accumulator

  β”œβ”€ MCP Server β€” 80+ tools (messaging, memory, Agent, Skill, inference, tasks, knowledge base, ERP), per-agent registration

  β”œβ”€ Evolution Engine β€” GVUΒ² dual-loop evolution + prediction-driven + MistakeNotebook

  β”œβ”€ Inference Engine β€” llama.cpp / mistral.rs / Exo P2P / llamafile / MLX / ONNX

  β”œβ”€ Voice Pipeline β€” ASR (SenseVoice / Whisper) + TTS (Piper / MiniMax) + VAD (Silero)

  β”œβ”€ Account Rotator β€” multi-OAuth + API Key rotation, budget tracking, health checks, Cross-Provider Failover

  β”œβ”€ Browser Automation β€” 5-layer auto-routing (API Fetch β†’ Scrape β†’ Headless β†’ Sandbox β†’ Computer Use)

  β”œβ”€ Worktree Isolation β€” Git worktree L0 sandbox, atomic merge, cap of 5 per Agent

  β”œβ”€ Wiki Knowledge Layer β€” L0-L3 four-tier knowledge architecture + trust weighting + FTS5 + auto-injection

  β”œβ”€ ACP/A2A Server β€” `duduclaw acp-server` stdio JSON-RPC 2.0, Zed/JetBrains/Neovim integration

  └─ Web Dashboard β€” React 19 SPA (23 pages), embedded in the binary via rust-embed

```



---






## Core Features



### Channels & Messaging



| Feature | Description |

|------|------|

| **Seven-channel support** | Telegram (long polling), LINE (webhook), Discord (Gateway WebSocket, op 6 RESUME + stall watchdog + 1-5s jitter), Slack (Socket Mode), WhatsApp (Cloud API), Feishu (Open Platform v2), WebChat (WebSocket) |

| **Per-Agent Bot** | Each Agent can have its own Bot Token, with multiple Agents running in parallel on the same platform |

| **Channel hot-start/stop** | Adding/removing channels in the Dashboard takes effect immediately, no gateway restart needed |

| **WebChat** | Built-in `/ws/chat` WebSocket endpoint, real-time conversation in the React frontend |

| **Generic Webhook** | `POST /webhook/{agent_id}` + HMAC-SHA256 signature verification |

| **Media Pipeline** | Automatic image resizing (max 1568px) + MIME detection + Vision integration |

| **Sticker system** | LINE sticker catalog + emotion detection + Discord emoji equivalence mapping |



### AI Execution & Inference



| Feature | Description |

|------|------|

| **MCP Server architecture** | `duduclaw mcp-server` provides 80+ tools covering messaging, memory, Agent management, inference, scheduling, the Skill marketplace, the task board, the shared knowledge base, and Odoo ERP. Registered in each agent directory's `.mcp.json` (Claude CLI `-p --dangerously-skip-permissions` only reads project-level settings), auto-created/repaired at gateway startup |

| **MCP Refresh Tokens** (v1.16.0) | Long-lived credentials backed by `~/.duduclaw/mcp_tokens.db` β€” token form `ddc_refresh__<64hex>`, 90-day lifespan, individually revocable, hash-only storage (the original token never lands on disk); `authenticate_from_env` routes credentials by prefix, the legacy `ddc__<32hex>` is fully preserved; the new CLI `duduclaw mcp { issue-refresh-token \| revoke-token \| list-tokens }` solves the pain of Claude Desktop silently disconnecting without retry after an auth-fail |

| **Multi-Runtime** | The `AgentRuntime` trait β€” four backends (Claude / Codex / Gemini / OpenAI-compat), `RuntimeRegistry` auto-detection, per-agent config |

| **Local inference engine** | Unified `InferenceBackend` trait β€” llama.cpp (Metal/CUDA/Vulkan) / mistral.rs (ISQ + PagedAttention) / Exo P2P cluster / llamafile / MLX (Apple Silicon) / OpenAI-compat HTTP |

| **Three-tier confidence routing** | LocalFast β†’ LocalStrong β†’ CloudAPI, auto-routed via heuristic confidence scoring, with CJK-aware token estimation |

| **InferenceManager** | Multi-mode auto-switching: Exo P2P β†’ llamafile β†’ Direct backend β†’ OpenAI-compat β†’ Cloud API, periodic health checks + automatic failover |

| **Native multi-turn Session** | Claude CLI `--resume` with a SHA-256 deterministic session ID + history-in-prompt fallback (auto-retry on account rotation/stale session); Hermes-style turn trimming (>800 chars, CJK-safe); Direct API "system_and_3" breakpoint cache strategy |

| **Session memory stack** | Instruction Pinning (Haiku extracts the core task from the first message β†’ injected at the tail of the session prompt) + Snowball Recap (a zero-cost `` prepended each turn) + P2 Key-Fact Accumulator (2-4 facts per turn β†’ FTS5 index β†’ top-3 injection, only 100-150 tokens vs MemGPT's 6,500 tokens, βˆ’87%) |

| **Claude CLI lightweight path** | `call_claude_cli_lightweight()` handles metadata tasks (compression, instruction/key-fact extraction) with `--effort medium --max-turns 1 --no-session-persistence --tools ""`, saving 25-40% in cost |

| **Claude CLI stabilization flags** | `--strict-mcp-config` (MCP isolation) + `--exclude-dynamic-system-prompt-sections` (cross-turn prompt stability, 10-15% token savings); `--bare` was removed in v1.8.11 because it broke the OAuth keychain |

| **Direct API** | Bypasses the CLI to call the Anthropic Messages API directly, reaching a 95%+ cache hit rate with `cache_control: ephemeral` |

| **Token compression** | Meta-Token (BPE-like 27-47%), LLMLingua-2 (2-5x lossy), StreamingLLM (infinite-length conversation) |

| **Cross-Provider Failover** | `FailoverManager` health tracking, cooldown, non-retryable error detection |

| **Cross-Platform PTY Pool** (v1.15.0) | An interactive REPL channel dedicated to OAuth accounts β€” cross-platform `portable-pty` (ConPTY on Win 10 1809+, openpty on Unix) + a sentinel-framed in-band response protocol (no scrollback scraping / no sidecar) + per-agent semaphore + idle eviction + health-check supervisor + restart policy. Off by default; enabled per-agent via `agent.toml [runtime] pty_pool_enabled = true`; an optional out-of-process mode (`worker_managed = true`) moves the pool to the `duduclaw-cli-worker` subprocess communicating over localhost JSON-RPC |

| **PTY Pool Observability** | Phase 8 production-rollout metrics β€” `pty_pool_*` Prometheus counters (acquires / cache-hit / spawn / three eviction reasons / 4 invoke outcomes / duration histogram) + `worker_health_misses_total` + `worker_restarts_total` + the `pty_pool_managed_worker_active` mode gauge + the `GET /api/runtime/status` JSON endpoint (loopback-only) |

| **Browser automation** | 5-layer routing (API Fetch β†’ Static Scrape β†’ Headless Playwright β†’ Sandbox Container β†’ Computer Use), deny-by-default |



### Voice & Multimedia



| Feature | Description |

|------|------|

| **ASR speech recognition** | ONNX SenseVoice (local) + Whisper.cpp (local) + OpenAI Whisper API |

| **TTS speech synthesis** | ONNX Piper (local) + MiniMax T2A |

| **VAD voice activity detection** | ONNX Silero VAD |

| **Discord voice channel** | Songbird integration, Discord voice conversation |

| **LiveKit voice room** | WebRTC multi-Agent voice conferencing |

| **ONNX embeddings** | BERT WordPiece tokenizer + ONNX Runtime vector embeddings |



### Agent Orchestration & Evolution



| Feature | Description |

|------|------|

| **Sub-Agent orchestration** | `create_agent` / `spawn_agent` / `list_agents` MCP tools + `reports_to` org hierarchy + D3.js architecture chart; the system prompt auto-injects a "## Your Team" sub-Agent roster + long report messages are auto-paginated (Discord 1900 / Telegram 4000 / LINE 4900 / Slack 3900 byte budget, labeled `πŸ“¨ **agent** ηš„ε›žε ± (1/N)`) |

| **Cross-system prompt injection** | CLAUDE.md + CONTRACT.toml (must_not/must_always) + SOUL.md + Wiki L0+L1 + key_facts top-3 + pinned_instructions are injected consistently across the CLI/channel/dispatcher paths, with behavior aligned across the four Claude/Codex/Gemini/OpenAI runtimes |

| **Orphan response recovery** | On dispatcher startup, `reconcile_orphan_responses` scans `bus_queue.jsonl` and atomically replays `agent_response` callbacks left over after crash/Ctrl+C/hotswap |

| **GVUΒ² dual-loop evolution** | Outer loop (Behavioral GVU β€” SOUL.md evolution) + inner loop (Task GVU β€” real-time task retry), with MistakeNotebook as cross-loop memory |

| **Prediction-driven evolution** | Active Inference + Dual Process Theory, ~90% of conversations at zero LLM cost; MetaCognition self-calibrates thresholds every 100 predictions |

| **4+2 layer verification** | L1-Format / L2-Metrics / **L2.5-MistakeRegression** / L3-LLMJudge / **L3.5-SandboxCanary** / L4-Safety, the first 4 layers at zero cost |

| **Adaptive Depth** | MetaCognition drives GVU iteration depth (3-7 rounds), auto-adjusted based on historical success rate |

| **Deferred GVU** | gradient accumulation + delayed retry (up to 3 deferrals, 9-21 effective iterations over a 72h span) |

| **ConversationOutcome** | Zero-LLM conversation outcome detection (TaskType / Satisfaction / Completion), bilingual zh-TW + en |

| **SOUL.md versioning** | 24h observation period + auto-rollback, atomic write (SHA-256 fingerprint) |

| **`SoulPatchOp::Consolidate`** (v1.16.0) | The structured patch path adds a "shrink invariant" variant β€” semantically equivalent to `Replace`, but `apply_patch_to_soul` rejects new content that isn't shorter than the existing body, so the LLM can self-trigger consolidation as SOUL.md approaches the 150-line / 8KB hard cap |

| **`agent_update_soul` trust chain** (v1.15.2) | After writing, automatically `soul_guard::accept_soul_change` syncs the integrity fingerprint + both success and all four rejection paths are written to `tool_calls.jsonl` (16-char hash prefix), patching the stored-vs-current drift and the backdoor-invisibility problem |

| **Agent-as-Evaluator** | An independent Evaluator Agent (Haiku for cost control) performs adversarial verification with a structured JSON verdict |

| **DelegationEnvelope** | Structured handoff protocol β€” context / constraints / task_chain / expected_output, backward-compatible with the Raw payload |

| **TaskSpec workflow** | Multi-step task planning β€” dependency-aware scheduling / auto-retry (3x) / replan (up to 2x) / persistence |

| **Orchestrator template** | 5-step planning strategy (Analyze β†’ Decompose β†’ Delegate β†’ Evaluate β†’ Synthesize) + complexity routing |

| **Skill lifecycle** | 7-stage management β€” Activation β†’ Compression β†’ Extraction β†’ Reconstruction β†’ Distillation β†’ Diagnostician β†’ Gap Analysis |

| **Skill auto-synthesis** | Detect repeated domain gaps β†’ synthesize new Skills from episodic memory β†’ sandbox trial (TTL-managed) β†’ cross-Agent graduation |

| **Task Board** | SQLite task management β€” status/priority/assignment tracking + real-time Activity Feed (WebSocket push) |

| **Autopilot rule engine** | Automated task delegation, notification, and Skill triggering β€” supports task creation/status change/channel message/idle detection/Cron schedule |

| **Shared knowledge base** | `~/.duduclaw/shared/wiki/` cross-Agent shared knowledge (SOPs, policies, product specs) + author attribution |

| **Wiki knowledge tiering** | Vault-for-LLM inspired β€” L0 Identity / L1 Core (auto-injected into every conversation) / L2 Context (updated daily) / L3 Deep (searched on demand), each page carrying a `trust` (0.0-1.0) weight; FTS5 unicode61 tokenizer supports CJK full-text search; `wiki_dedup` detects duplicate pages, `wiki_graph` outputs a Mermaid knowledge graph |

| **Wiki auto-injection** | `build_system_prompt()` automatically injects L0+L1 pages into WIKI_CONTEXT; covers all three system-prompt assembly paths (CLI interaction, channel reply, dispatcher/cron), consistent across the four Claude/Codex/Gemini/OpenAI runtimes |

| **Git Worktree L0 isolation** | An independent worktree workspace per task (cheaper than a container sandbox), atomic merge (dry-run pre-check + global `Mutex`), friendly `wt/{agent_id}/{adjective}-{noun}` branch names; cap of 5 per agent, 20 globally; Snap workflow: create β†’ execute β†’ inspect β†’ merge/cleanup |

| **ACP/A2A Protocol Server** | `duduclaw acp-server` provides a stdio JSON-RPC 2.0 server (`agent/discover` / `tasks/send` / `tasks/get` / `tasks/cancel`), compatible with the Agent Client Protocol, supporting Zed / JetBrains / Neovim IDE integration; outputs a `.well-known/agent.json` AgentCard |

| **Reminder scheduling** | One-time reminders (relative time `5m`/`2h`/`1d` or ISO 8601 absolute time), `direct` static message or `agent_callback` wake-up mode |



### Reliability & Governance (added in v1.9.x)



| Feature | Description |

|------|------|

| **`duduclaw-durability` crate** | Five persistence mechanisms β€” idempotency key management, exponential-backoff retry (jitter), three-state circuit breaker (Closed/Open/HalfOpen), checkpoint resume, Dead Letter Queue for terminal-failure messages |

| **`duduclaw-governance` crate** | PolicyRegistry + 4 PolicyTypes (Rate/Permission/Quota/Lifecycle) + quota_manager (soft/hard quotas) + error_codes (standardized QUOTA_EXCEEDED / POLICY_DENIED) + YAML hot reload + audit log |

| **LLM Fallback** | Auto-switches to a fallback model on primary-model timeout/503/429/overloaded; the pure functions `is_llm_fallback_error` / `should_attempt_model_fallback`, with the hard deadline uniformly returning a hard-timeout error to trigger fallback |

| **Evolution Events system** | 30+ event schemas, an async emitter (batch + retry), a query interface, reliability mechanisms; HTTP endpoints exposed on the gateway, visualized in the Web ReliabilityPage |

| **MCP HTTP/SSE Transport** (W20-P1/P2) | `duduclaw http-server --bind 127.0.0.1:8765` β€” `POST /mcp/v1/call` (single JSON-RPC tool call) + `GET /mcp/v1/stream` (SSE long-lived event stream) + `POST /mcp/v1/stream/call` (async + SSE push) + Bearer auth + token bucket rate limit |

| **Memory MCP scope enforcement** | The `memory:read` / `memory:write` scopes are checked at the execute() entry point of `store/read/search`, patching the pre-v1.9.3 auth gap where any valid API Key could bypass scope |

| **LOCOMO memory evaluation** | `memory_eval/` β€” retrieval_accuracy / retention_rate / locomo_integrity_check + cron_runner (daily 03:00 UTC) + a 5-minute smoke_test P0 + a 200-entry golden QA gold set |



### Security



| Feature | Description |

|------|------|

| **Claude Code Security Hooks** | Three-phase progressive defense β€” Layer 1 blacklist (<50ms) β†’ Layer 2 obfuscation detection (YELLOW+) β†’ Layer 3 Haiku AI judgment (RED only) |

| **Threat-level state machine** | GREEN β†’ YELLOW β†’ RED with auto-escalation/degradation, dropping one level after 24h with no events |

| **SOUL.md drift detection** | Real-time SHA-256 fingerprint comparison |

| **Prompt Injection scanning** | 6 rule categories, XML delimiter tags for injection resistance |

| **Secret leak scanning** | 20+ patterns (Anthropic/OpenAI/AWS/GitHub/Slack/Stripe/DB URL, etc.) |

| **Sensitive file protection** | Read/Write/Edit three-way protection of `secret.key`, `.env*`, `SOUL.md`, `CONTRACT.toml` |

| **Behavioral contracts** | `CONTRACT.toml` defines `must_not` / `must_always` boundaries + `duduclaw test` red-team testing (9 scenarios) |

| **Unified multi-source audit log** | `audit.unified_log` merges 4 JSONL streams (`security_audit.jsonl` / `tool_calls.jsonl` / `channel_failures.jsonl` / `feedback.jsonl`) into a unified envelope (timestamp / source / event_type / agent_id / severity / summary / details); the Logs page supports source filtering, a severity dropdown, and live/historical tabs |

| **JSONL audit log** | Async writes, format-compatible with the Rust `AuditEvent` schema |

| **CJK-Safe string slicing** | The new `truncate_bytes` / `truncate_chars` module replaces 31 instances of `s[..s.len().min(N)]` byte-index slicing (fixing the v1.8.11 multi-byte codepoint panic) |

| **Per-Agent key isolation** | AES-256-GCM encrypted storage, keys invisible between agents |

| **Container sandbox** | Docker / Apple Container (`--network=none`, tmpfs, read-only rootfs, 512MB limit) |

| **Browser automation** | 5-layer routing (API Fetch β†’ Static Scrape β†’ Headless β†’ Sandbox β†’ Computer Use), deny-by-default |



### Accounts & Cost



| Feature | Description |

|------|------|

| **Dual-mode account rotation** | OAuth subscription (Pro/Team/Max) + API Key hybrid β€” 4 strategies (Priority/LeastCost/Failover/RoundRobin) |

| **Health tracking** | Rate-limit cooldown (2min), billing-exhaustion cooldown (24h), token-expiry tracking (30d/7d warnings) |

| **Cost telemetry** | SQLite token tracking, cache efficiency analysis, 200K price-cliff warning, adaptive routing (auto-switch to local when cache efficiency <30%) |

| **Claude CLI binary probing** | `which_claude()` / `which_claude_in_home()` scan Homebrew (Intel + Apple Silicon) / Bun / Volta / npm-global / `.claude/bin` / `.local/bin` / asdf shims / NVM version directories, fixing the binary-not-found issue at launchd startup |

| **Structured failure classification** | The `FailureReason` enum (RateLimited / Billing / Timeout / BinaryMissing / SpawnError / EmptyResponse / NoAccounts / Unknown) + category-specific zh-TW messages + `channel_failures.jsonl` audit records |



### Integrations & Extensions



| Feature | Description |

|------|------|

| **Odoo ERP integration** | `duduclaw-odoo` middleware β€” 15 MCP tools (CRM/Sales/Inventory/Accounting/generic search-report), supporting CE/EE, with EditionGate auto-detection. The Dashboard settings page supports **test-before-save** (v1.13.1, falls back to the stored key when the credential is left blank) + **per-agent credential isolation** (v1.11.0, `OdooConnectorPool` replaces the global admin singleton) |

| **Skill marketplace** | GitHub Search API live indexing + 24h local cache + security scan + Dashboard marketplace page |

| **Prometheus metrics** | `GET /metrics` β€” requests, tokens, duration histogram, channel status |

| **CronScheduler** | `cron_tasks.jsonl` + cron expressions, scheduled tasks fired automatically |

| **ONNX embeddings** | BERT WordPiece tokenizer + ONNX Runtime vector embeddings, with semantic search support |

| **Experiment Logger** | Trajectory recording, supporting RL/RLHF offline analysis |

| **Memory Decay scheduling** | Background `run_decay` every 24h: low-importance + 30+ days β†’ archive; 90+ days archived β†’ permanent deletion |

| **RL Trajectory Collector** | Writes to `~/.duduclaw/rl_trajectories.jsonl` during channel interactions; the `duduclaw rl` CLI provides export/stats/reward functions, with a composite reward (outcomeΓ—0.7 + efficiencyΓ—0.2 + overlongΓ—0.1) |

| **Marketplace RPC** | `marketplace.list` serves a real MCP catalog (Playwright, Browserbase, Filesystem, GitHub, Slack, Postgres, SQLite, Memory, Fetch, Brave Search), mergeable with user-defined entries via `~/.duduclaw/marketplace.json` |

| **Partner Portal** | SQLite `PartnerStore` (`~/.duduclaw/partner.db`) + 7 RPCs (profile/stats/customers CRUD) + sales statistics |



### Web Dashboard



| Feature | Description |

|------|------|

| **Tech stack** | React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui, warm amber color scheme |

| **24 pages** | Dashboard / Agents / Channels / Accounts / Memory / Security / Settings / OrgChart / SkillMarket / Logs / WebChat / OnboardWizard / Billing / License / Report / PartnerPortal / Marketplace / KnowledgeHub / Odoo / Login / Users / Analytics / Export / **Reliability** (added in v1.9.4) |

| **Reliability dashboard** | circuit breaker status / retry stats / DLQ queue depth / real-time evolution events data; the `/reliability` route, integrating the `getEvolutionEvents` / `getReliabilityStats` / `getDlqItems` APIs |

| **Real-time logs** | BroadcastLayer tracing β†’ WebSocket push, WS heartbeat ping/pong (server 30s / client 25s) + 60s idle close |

| **Logs history page rewrite** | Source-filter chips (All / Security / Tool calls / Channel failures / Feedback) + live entry-count + severity dropdown + severity-colored left border (emerald/amber/rose) + click-to-expand JSON details |

| **Memory page Key Insights** | The fourth tab presents the structured insights accumulated by the P2 Key-Fact Accumulator (the `key_facts` table) + `access_count` badge + timestamp + source metadata |

| **Memory page evolution history** | SOUL.md version history + before/after metric diffs (positive feedback / prediction error / user corrections) + status badges (Confirmed / RolledBack / Observing) |

| **Toast notification system** | Module-scoped event bus, max-5 queue, auto-dismiss, warm stone/amber/emerald/rose variants, respects `prefers-reduced-motion` |

| **Org chart** | D3.js interactive Agent hierarchy visualization |

| **Light/dark toggle** | Follows system preference, supports manual toggle |

| **Internationalization** | zh-TW / en / ja-JP trilingual support (600+ translation keys) |

| **Skill Market three tabs** | Marketplace / Shared Skills / My Skills three-tab architecture + Skill adoption flow |

| **Autopilot settings** | Automation rule creation/management/monitoring + history review |

| **Session Replay** | Conversation replay component, supports timeline view |



---






## Comparison



| | **DuDuClaw** | **OpenClaw** | **IronClaw** | **Moltis** | **Dify** |

|---|---|---|---|---|---|

| Language | Rust | TypeScript | Rust | Rust | Python |

| Channels | 7 | 25+ | 8 | 5 | 0 (API) |

| Multi-Runtime | **4 backends (Claude/Codex/Gemini/OpenAI)** | - | - | - | Multi-LLM |

| MCP Server | **80+ tools** | - | - | - | - |

| Self-evolution engine | **GVUΒ² dual-loop** | - | - | - | - |

| Local inference | **6 backends + three-tier confidence routing** | - | - | - | - |

| Voice (ASR/TTS) | **4 ASR + 4 TTS providers** | - | - | - | - |

| Token compression | **3 strategies** | - | - | - | - |

| Browser automation | **5-layer routing** | - | - | - | - |

| Cost telemetry | **Cache efficiency analysis** | - | Basic | Basic | Basic |

| Behavioral contracts | **CONTRACT.toml + red team** | - | WASM sandbox | - | - |

| ERP integration | **Odoo 15 tools** | - | - | - | - |

| Security audit | **Three-layer defense + Hooks** | CVE-2026-25253 | WASM | Basic | Medium |

| License | **Apache 2.0 (Open Core)** | MIT | Open source | Open source | $59+/month |



---






## Agent Directory Structure



Each Agent is a folder, fully compatible with the Claude Code structure:



```

~/.duduclaw/agents/

β”œβ”€β”€ dudu/                    # Main Agent

β”‚   β”œβ”€β”€ .claude/             # Claude Code settings

β”‚   β”‚   └── settings.local.json

β”‚   β”œβ”€β”€ .mcp.json            # MCP Server config (DuDuClaw platform tools + agent-specific MCP such as Playwright)

β”‚   β”‚                        # auto-created/repaired at gateway startup; Claude CLI `-p` mode only reads this file

β”‚   β”œβ”€β”€ SOUL.md              # Persona definition (SHA-256 protected)

β”‚   β”œβ”€β”€ CLAUDE.md            # Claude Code guidance (includes the CLAUDE_WIKI template)

β”‚   β”œβ”€β”€ CONTRACT.toml        # Behavioral contract (must_not / must_always), auto-injected into the system prompt

β”‚   β”œβ”€β”€ agent.toml           # DuDuClaw config (model, budget, heartbeat, runtime, capabilities)

β”‚   β”œβ”€β”€ SKILLS/              # Skill set (can be auto-generated by the evolution engine)

β”‚   β”œβ”€β”€ wiki/                # Wiki knowledge base (L0-L3 tiering + trust weighting + FTS5)

β”‚   β”œβ”€β”€ memory/              # Daily notes + memory.db (prediction error) + key_facts table

β”‚   β”œβ”€β”€ tasks/               # TaskSpec workflow persistence (JSON)

β”‚   └── state/               # Runtime state (SQLite: sessions.pinned_instructions, etc.)

β”‚

└── coder/                   # Another Agent

    └── ...

```



Use `duduclaw migrate` to automatically convert a legacy `agent.toml` to the Claude Code-compatible format.



---






## Security Hooks



DuDuClaw builds a three-phase progressive defense on top of Claude Code's Hook system:



```

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”

  SessionStart ──→  β”‚ session-init.sh                     β”‚  Key permission verification + environment init

                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”

  UserPrompt   ──→  β”‚ inject-contract.sh                  β”‚  CONTRACT.toml rule injection

                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”

  PreToolUse   ──→  β”‚ bash-gate.sh (Bash)                 β”‚  Layer 1: blacklist (<50ms)

     (Bash)         β”‚   β”œβ”€ Layer 2: obfuscation detect (YELLOW+)    β”‚  Layer 2: base64/eval/exfiltration

                    β”‚   └─ Layer 3: Haiku AI (RED only)   β”‚  Layer 3: AI safety judgment

                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”

  PreToolUse   ──→  β”‚ file-protect.sh β†’ ai-review.sh     β”‚  Sensitive file protection + AI review

  (Write|Edit|Read) β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”

  PostToolUse  ──→  β”‚ secret-scanner.sh β†’ audit-logger.sh β”‚  Secret scan β†’ async audit

                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”

  Stop         ──→  β”‚ threat-eval.sh                      β”‚  Threat-level re-evaluation

                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”

  ConfigChange ──→  β”‚ config-guard.sh                     β”‚  Config tampering detection

                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

```



### Threat-level state machine



| Level | Trigger | Defense behavior |

|------|---------|---------|

| **GREEN** (default) | Normal operation | Layer 1 blacklist + file protection + Secret scan |

| **YELLOW** | β‰₯ 2 interceptions within 1 hour | +Layer 2 obfuscation detection + external network restriction |

| **RED** | Injection/eval attack detected | +Layer 3 Haiku AI judgment of all commands + AI file review |



Degradation: automatically drops one level after 24 hours with no events (RED→YELLOW→GREEN).



---






## Installation



### npm (recommended, all platforms incl. Windows)



```bash

npm install -g duduclaw

```



After installation it automatically downloads the **precompiled binary** for your platform (supports macOS ARM64/x64, Linux x64/ARM64, Windows x64) β€” **no compiler, no Rust, no MSVC Build Tools required**. Windows users only need [Node.js](https://nodejs.org/) installed first; that is the only prerequisite.



> **⚠️ If installation asks you to install Rust / MSVC Build Tools (~2GB) and compile (~1.5h), you're on the wrong path.**

> That's the "[Build from source](#build-from-source)" path, only needed by contributors who modify the code. For normal use, always use `npm install -g duduclaw` above (or Homebrew / one-line install below) β€” it downloads the official prebuilt binary directly.



### Homebrew (macOS / Linux)



```bash

brew install zhixuli0406/tap/duduclaw

```



### One-line install



**macOS / Linux:**



```bash

curl -fsSL https://raw.githubusercontent.com/zhixuli0406/DuDuClaw/main/scripts/install.sh | sh

```



**Windows (PowerShell):**



```powershell

irm https://raw.githubusercontent.com/zhixuli0406/DuDuClaw/main/scripts/install.ps1 | iex

```



> The one-line installer auto-detects the **latest release** and downloads the prebuilt binary for your platform β€” also compile-free. It only offers a source build if the GitHub download fails (in which case prefer `npm install -g duduclaw`). Pin a specific version with the `DUDUCLAW_VERSION` environment variable.



### Desktop app



Besides the CLI, a native **desktop app** (Tauri) is available β€” it auto-starts the local gateway on launch, with a one-click Workspace (simple) ⇄ Dashboard (advanced) toggle. Download the build for your platform from [**Releases**](https://github.com/zhixuli0406/DuDuClaw/releases):



| Platform | File | Notes |

|------|------|------|

| macOS (Apple Silicon) | `DuDuClaw_*_aarch64.dmg` | βœ… Signed + Apple-notarized, opens with no warning |

| macOS (Intel) | `DuDuClaw_*_x64.dmg` | βœ… Signed + Apple-notarized, opens with no warning |

| Windows (x64) | `DuDuClaw_*_x64_en-US.msi` | ⚠️ Unsigned β€” see below |

| Linux | `*_amd64.AppImage` / `*_amd64.deb` | Unsigned (not required) |



> The desktop app **shares** `~/.duduclaw` with the CLI (same config / SQLite / wiki); if a gateway is already running it attaches instead of starting a second one.



#### ⚠️ Windows: SmartScreen "Unknown publisher" warning β€” how to run it



The Windows installer is **not yet code-signed with an Authenticode certificate**, so **Microsoft Defender SmartScreen will warn** ("Windows protected your PC" / "Unknown publisher"). **This is not malware β€” it's just unsigned.** To run it:



1. Double-click the `.msi` β†’ the blue SmartScreen dialog appears

2. Click **"More info"**

3. Click **"Run anyway"**



**To avoid the warning entirely**, two options with no signing concerns:



- Use the CLI instead: `npm install -g duduclaw` (full-featured, includes the dashboard)

- Wait for a signed build: a Windows Authenticode certificate is being evaluated (cloud signing; see [`docs/guides/desktop-unblock.md`](docs/guides/desktop-unblock.md) gate C)



> **macOS has no such issue** β€” it's Developer ID signed + Apple-notarized, so a clean machine opens it with no warning (`spctl -a` returns `accepted / Notarized Developer ID`).



### Python SDK (optional library, not a CLI)



> **Important**: The core gateway / CLI (the `duduclaw` command) is a **Rust binary** β€” installing it via **npm** or **Homebrew** above gives you the **complete feature set**. Skill security scanning and channel replies are all handled by Rust-native paths, so **no Python dependency is required**.

> The `duduclaw` package on PyPI is a **pure Python library** (for `import duduclaw`) and ships **no command-line tool**; consequently `pipx install duduclaw` fails (No apps associated with package) β€” this is expected.



`pip install duduclaw` is **optional for core functionality** β€” only needed when:



- You want to `import duduclaw` in your own Python code (the agents / channels / mcp / memory_eval modules).

- You run the standalone memory-evaluation tooling (LOCOMO).



> **Advanced local inference (MLX reflections / LLMLingua-2 compression)** is a separate opt-in feature set that depends on ML packages such as `mlx_lm` and `llmlingua` β€” **not** on the `duduclaw` PyPI package. Install those individually per `inference.toml` when needed.



To install the optional library:



```bash

pip install duduclaw

```



This command installs the following dependencies:



| Package | Minimum version | Purpose |

|------|---------|------|

| `anthropic` | β‰₯ 0.40 | Direct Claude API calls from your own Python code |

| `httpx` | β‰₯ 0.27 | Async HTTP client (account rotation, health checks) |

| `pyyaml` | β‰₯ 6.0 | Config file parsing |



#### macOS (Homebrew Python) / other externally-managed environments



If the system reports `error: externally-managed-environment` ([PEP 668](https://peps.python.org/pep-0668/)), installing into the system Python is blocked. Use a virtual environment instead:



```bash

# venv

python3 -m venv .venv && source .venv/bin/activate

pip install --upgrade duduclaw



# or use uv (already adopted by this project, much faster)

uv venv && uv pip install --upgrade duduclaw

```



Verify the installed version:



```python

import duduclaw

print(duduclaw.__version__)   # reflects the actually installed PyPI version

```



> `__version__` is read dynamically from the installed package metadata (`pyproject.toml`) via `importlib.metadata`; a source checkout (not pip-installed) falls back to a built-in string, kept in sync with the other platform versions by `scripts/release.sh`'s drift guard.



For development environments, additionally install:



```bash

pip install duduclaw[dev]

# Includes: pytest>=8, pytest-asyncio>=0.24, ruff>=0.8

```



### Build from source



```bash

git clone https://github.com/zhixuli0406/DuDuClaw.git

cd DuDuClaw



# (Optional) only needed for the importable Python library / memory-eval tooling; the core build does not require it

# pip install duduclaw



# Build the Dashboard

cd web && npm ci --legacy-peer-deps && npm run build && cd ..



# Build the Rust binary (with Dashboard)

cargo build --release -p duduclaw-cli -p duduclaw-gateway --features duduclaw-gateway/dashboard



# First-time setup

./target/release/duduclaw onboard



# Start

./target/release/duduclaw run

```



> **Prerequisites**: [Rust](https://rustup.rs/) 1.85+, [Python](https://www.python.org/) 3.9+, [Node.js](https://nodejs.org/) 20+, and at least one AI CLI: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli) (one or more)



---






## CLI Commands



```

duduclaw onboard             # Interactive first-time setup

duduclaw run                 # One-click start (gateway + channels + heartbeat + cron + dispatcher)

duduclaw migrate             # Convert agent.toml to Claude Code format

duduclaw mcp-server          # Start the MCP Server (for the AI Runtime, stdio JSON-RPC 2.0)

duduclaw http-server         # Start the MCP HTTP/SSE Transport (Bearer auth, default 127.0.0.1:8765)

duduclaw acp-server          # Start the ACP/A2A Server (IDE integration: Zed/JetBrains/Neovim)

duduclaw gateway             # Start only the WebSocket gateway server



duduclaw agent               # CLI interactive conversation

duduclaw agent list          # List all Agents

duduclaw agent create        # Create a new Agent (industry template optional)

duduclaw agent inspect       # View Agent details

duduclaw agent pause         # Pause an Agent

duduclaw agent resume        # Resume an Agent

duduclaw agent edit          # Edit Agent settings

duduclaw agent remove        # Remove an Agent



duduclaw test         # Red-team security test (9 built-in scenarios + JSON report)

duduclaw status              # System health snapshot

duduclaw doctor              # Health diagnostics

duduclaw wizard              # Interactive industry-template setup

duduclaw evolution finalize  # One-shot recovery of overdue SOUL.md observation windows (--dry-run / --agent )



duduclaw rl export           # Export RL trajectory (~/.duduclaw/rl_trajectories.jsonl)

duduclaw rl stats            # Per-Agent trajectory statistics

duduclaw rl reward           # Compute composite reward (outcomeΓ—0.7 + efficiencyΓ—0.2 + overlongΓ—0.1)



duduclaw service install     # Install as a system service

duduclaw service start/stop  # Start/stop the system service

duduclaw service status      # Service status

duduclaw service logs        # Service logs

duduclaw service uninstall   # Remove the system service



duduclaw license activate    # Activate license

duduclaw license status      # License status

duduclaw license verify      # Verify license

duduclaw update              # Check for and install updates

duduclaw version             # Version info

```



---






## Project Structure



```

DuDuClaw/

β”œβ”€β”€ crates/                         # Rust crates (20)

β”‚   β”œβ”€β”€ duduclaw-core/              # Shared types, traits (Channel, MemoryEngine), error definitions

β”‚   β”œβ”€β”€ duduclaw-agent/             # Agent registry, heartbeat, budget, contract, skill loader/registry

β”‚   β”œβ”€β”€ duduclaw-auth/              # Multi-user auth (Argon2 passwords, JWT, ACL role permissions)

β”‚   β”œβ”€β”€ duduclaw-security/          # AES-256-GCM, SOUL guard, input guard, audit, key vault

β”‚   β”œβ”€β”€ duduclaw-container/         # Docker / Apple Container / WSL2 sandbox execution

β”‚   β”œβ”€β”€ duduclaw-memory/            # SQLite + FTS5 full-text search + vector embeddings + eval batch query API

β”‚   β”œβ”€β”€ duduclaw-inference/         # Local inference engine (llama.cpp / mistral.rs / ONNX / Exo / llamafile)

β”‚   β”œβ”€β”€ duduclaw-gateway/           # Axum server, 7 channels, session, GVUΒ², prediction, cron, dispatcher, LLM fallback, evolution events, PTY pool integration

β”‚   β”œβ”€β”€ duduclaw-bus/               # tokio broadcast + mpsc message routing

β”‚   β”œβ”€β”€ duduclaw-bridge/            # PyO3 Rust↔Python bridge layer

β”‚   β”œβ”€β”€ duduclaw-odoo/              # Odoo ERP middleware (JSON-RPC, CE/EE, 15 MCP tools)

β”‚   β”œβ”€β”€ duduclaw-cli/               # clap CLI entry + MCP server (stdio + HTTP/SSE) + migrate + test

β”‚   β”œβ”€β”€ duduclaw-dashboard/         # rust-embed embedded React SPA

β”‚   β”œβ”€β”€ duduclaw-desktop/           # Desktop wrapper (macOS/Windows/Linux)

β”‚   β”œβ”€β”€ duduclaw-durability/        # Durability framework (idempotency / retry / circuit breaker / checkpoint / DLQ) β€” added in v1.9.4

β”‚   β”œβ”€β”€ duduclaw-governance/        # PolicyRegistry / quota_manager / error_codes / audit / approval β€” added in v1.9.4

β”‚   β”œβ”€β”€ duduclaw-identity/          # IdentityProvider trait + Wiki/Notion/Chained three implementations β€” added in v1.11.0

β”‚   β”œβ”€β”€ duduclaw-redaction/         # Source-aware redaction + reversible vault (AES-256-GCM) + 5 profiles + JSONL audit β€” added in v1.14.0

β”‚   β”œβ”€β”€ duduclaw-cli-runtime/       # Cross-platform PTY pool runtime (portable-pty / sentinel-framed) β€” added in v1.15.0

β”‚   └── duduclaw-cli-worker/        # Standalone PTY pool worker subprocess (localhost JSON-RPC + Bearer token) β€” added in v1.15.0

β”‚

β”œβ”€β”€ python/duduclaw/                # Python extension layer

β”‚   β”œβ”€β”€ channels/                   # LINE / Telegram / Discord channel plugins

β”‚   β”œβ”€β”€ sdk/                        # Claude Code SDK chat + multi-account rotation

β”‚   β”œβ”€β”€ evolution/                  # Skill Vetter security scan

β”‚   β”œβ”€β”€ tools/                      # Agent dynamic management tools

β”‚   β”œβ”€β”€ agents/                     # capability manifest + capability-based router + memory_resolver (v1.9.4)

β”‚   β”œβ”€β”€ mcp/                        # MCP API Key auth (with key masking) + memory tools (store/read/search/namespace/quota)

β”‚   └── memory_eval/                # LOCOMO memory evaluation (retrieval/retention + cron + 200 golden QA) β€” added in v1.9.4

β”‚

β”œβ”€β”€ npm/                            # npm published packages

β”‚   β”œβ”€β”€ duduclaw/                   # Main package (platform-agnostic wrapper + postinstall binary download)

β”‚   β”œβ”€β”€ darwin-arm64/               # macOS Apple Silicon precompiled binary

β”‚   β”œβ”€β”€ darwin-x64/                 # macOS Intel precompiled binary

β”‚   β”œβ”€β”€ linux-x64/                  # Linux x86-64 precompiled binary

β”‚   β”œβ”€β”€ linux-arm64/                # Linux ARM64 precompiled binary

β”‚   └── win32-x64/                  # Windows x64 precompiled binary

β”‚

β”œβ”€β”€ web/                            # React Dashboard

β”‚   └── src/

β”‚       β”œβ”€β”€ components/             # UI components (OrgChart, ApprovalModal, SessionReplay)

β”‚       β”œβ”€β”€ pages/                  # 24 pages (including ReliabilityPage added in v1.9.4)

β”‚       β”œβ”€β”€ stores/                 # Zustand state management (8 stores)

β”‚       β”œβ”€β”€ lib/                    # API client (WebSocket JSON-RPC + evolution events / reliability HTTP)

β”‚       └── i18n/                   # zh-TW / en / ja-JP

β”‚

β”œβ”€β”€ templates/                      # Industry templates + Agent role templates

β”‚   β”œβ”€β”€ restaurant/                 # Restaurant (customer service, reservations, FAQ, proactive push)

β”‚   β”œβ”€β”€ manufacturing/              # Manufacturing (equipment monitoring, SOP, anomaly alerts)

β”‚   β”œβ”€β”€ trading/                    # Trading (quotes, orders, inventory, price lists)

β”‚   β”œβ”€β”€ evaluator/                  # Evaluator Agent (adversarial verification)

β”‚   β”œβ”€β”€ orchestrator/               # Orchestrator Agent (task orchestration)

β”‚   └── wiki/                       # Wiki knowledge base template

β”‚

β”œβ”€β”€ .claude/                        # Claude Code Hook security system

β”‚   β”œβ”€β”€ settings.local.json         # Hook config (6 events Γ— 10 scripts)

β”‚   └── hooks/                      # Three-phase progressive defense scripts

β”‚

β”œβ”€β”€ docs/                           # Public documentation

β”‚   β”œβ”€β”€ spec/                       # Format specs (SOUL.md / CONTRACT.toml)

β”‚   β”œβ”€β”€ api/                        # WebSocket RPC + OpenAPI spec

β”‚   β”œβ”€β”€ guides/                     # Development guides (custom MCP tools, etc.)

β”‚   └── *.md                        # Architecture, deployment, evolution engine, etc.

β”‚

β”œβ”€β”€ ARCHITECTURE.md                 # Complete architecture design document

└── CLAUDE.md                       # AI collaboration design context

```



---






## Technical Decisions



| Item | Choice | Rationale |

|------|------|------|

| AI conversation | **Multi-Runtime (Claude / Codex / Gemini CLI)** | Not tied to a single provider; auto-detection + per-agent config |

| Core language | **Rust** | Memory safety, high performance, single-binary deployment |

| Extension language | **Python (PyO3)** | Claude Code SDK integration, channel-plugin flexibility |

| Frontend framework | **React 19 + TypeScript** | Real-time data updates, mature ecosystem |

| UI style | **shadcn/ui + Tailwind CSS 4** | Warm, customizable, good performance |

| Database | **SQLite + FTS5** | Zero dependency, embedded, full-text search |

| Tool protocol | **MCP (Model Context Protocol)** | Native Claude Code support, stdin/stdout JSON-RPC |

| Local inference | **ONNX Runtime + llama.cpp** | Cross-platform, Metal/CUDA/Vulkan GPU acceleration |

| Speech recognition | **SenseVoice + Whisper.cpp** | Multilingual, local offline, zero API cost |

| Real-time communication | **WebRTC (LiveKit)** | Low-latency voice, multi-party conferencing |



---






## Testing



```bash

# Rust tests

cargo test --workspace --exclude duduclaw-bridge



# Python tests

pip install pytest pytest-asyncio ruff

ruff check python/

pytest tests/python/ -v



# Frontend type checking

cd web && npx tsc --noEmit

```



---






## Documentation



- [ARCHITECTURE.md](ARCHITECTURE.md) β€” Complete system architecture design

- [CLAUDE.md](CLAUDE.md) β€” AI collaboration design context and principles

- [CHANGELOG.md](CHANGELOG.md) β€” Version change log

- [docs/features/README.md](docs/features/README.md) β€” Detailed feature breakdown (19 articles, with zh-TW / ja-JP translations)

- [docs/features/feature-inventory.md](docs/features/feature-inventory.md) β€” Complete feature inventory

- [docs/spec/soul-md-spec.md](docs/spec/soul-md-spec.md) β€” SOUL.md format spec v1.0

- [docs/spec/contract-toml-spec.md](docs/spec/contract-toml-spec.md) β€” CONTRACT.toml format spec v1.0

- [docs/api/README.md](docs/api/README.md) β€” WebSocket RPC protocol + JSON-RPC 2.0 interface

- [docs/architecture/evolution-engine.md](docs/architecture/evolution-engine.md) β€” Evolution Engine v2 design document

- [docs/guides/deployment-guide.md](docs/guides/deployment-guide.md) β€” Production deployment guide

- [docs/guides/development-guide.md](docs/guides/development-guide.md) β€” Developer setup and Agent development

- [docs/guides/custom-mcp-tool.md](docs/guides/custom-mcp-tool.md) β€” Custom MCP tool tutorial



---






## License



**Open Core model** β€” the core code is licensed under [Apache License 2.0](LICENSE), completely free to use, modify, and distribute.



Commercial value-add modules (the `commercial/` directory) are closed-source and paid, including: industry templates, evolution parameter sets, the enterprise dashboard, and license verification.



See [LICENSING.md](LICENSING.md) for details.



---





  🐾 Built with louis.li