{"id":47636801,"url":"https://github.com/zhixuli0406/duduclaw","last_synced_at":"2026-07-02T16:01:04.699Z","repository":{"id":346162124,"uuid":"1182130315","full_name":"zhixuli0406/DuDuClaw","owner":"zhixuli0406","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-27T02:09:06.000Z","size":31129,"stargazers_count":43,"open_issues_count":2,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T02:10:01.893Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhixuli0406.png","metadata":{"files":{"readme":"README.en.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T04:35:01.000Z","updated_at":"2026-06-27T02:09:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zhixuli0406/DuDuClaw","commit_stats":null,"previous_names":["zhixuli0406/duduclaw"],"tags_count":181,"template":false,"template_full_name":null,"purl":"pkg:github/zhixuli0406/DuDuClaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhixuli0406%2FDuDuClaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhixuli0406%2FDuDuClaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhixuli0406%2FDuDuClaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhixuli0406%2FDuDuClaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhixuli0406","download_url":"https://codeload.github.com/zhixuli0406/DuDuClaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhixuli0406%2FDuDuClaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35053492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-04-02T00:19:37.860Z","updated_at":"2026-07-02T16:01:04.684Z","avatar_url":"https://github.com/zhixuli0406.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DuDuClaw 🐾\n\n\u003cdiv align=\"center\"\u003e\n\n[繁體中文](README.md) · **English** · [日本語](README.ja.md)\n\n\u003c/div\u003e\n\n\u003e **Multi-Runtime AI Agent Platform** — unifying the three major CLIs (Claude / Codex / Gemini) to build your multi-channel AI assistant\n\n[![CI](https://github.com/zhixuli0406/DuDuClaw/actions/workflows/ci.yml/badge.svg)](https://github.com/zhixuli0406/DuDuClaw/actions/workflows/ci.yml)\n[![Rust](https://img.shields.io/badge/Rust-2024_edition-orange?logo=rust)](https://www.rust-lang.org/)\n[![Python](https://img.shields.io/badge/Python-3.9+-blue?logo=python)](https://www.python.org/)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.30.1-blue)](https://github.com/zhixuli0406/DuDuClaw/releases)\n[![npm](https://img.shields.io/npm/v/duduclaw?logo=npm)](https://www.npmjs.com/package/duduclaw)\n[![PyPI](https://img.shields.io/pypi/v/duduclaw?logo=pypi)](https://pypi.org/project/duduclaw/)\n\n---\n\n## 🔒 Trust \u0026 Security\n\nThis is an open-source project — here's full transparency on what you're installing.\n\n### Why is a \"new\" npm package already at version 1.21+?\n\nDuDuClaw had several months of intensive development in a private repository (400+ commits) before\ngoing public. See the [git log](https://github.com/zhixuli0406/DuDuClaw/commits/main) for full history.\n\n### What's inside the npm package?\n\n- A small JS wrapper that only invokes the platform-specific Rust binary\n- The platform binary ships via npm `optionalDependencies` (`@duduclaw/\u003cplatform\u003e`) —\n  **no postinstall script downloads and executes external code from arbitrary URLs**\n- `postinstall` only checks that the platform package is present (see\n  [`npm/duduclaw/scripts/install.js`](npm/duduclaw/scripts/install.js)) — it downloads and executes nothing\n- GitHub Release binaries ship with SHA-256 checksums\n\n### Building from source (if you don't trust the prebuilt binary)\n\n```bash\ngit clone https://github.com/zhixuli0406/DuDuClaw\ncd DuDuClaw\ncargo build --release\n```\n\n### Binary verification\n\nEvery release ships with SHA-256 checksums and a keyless [cosign](https://github.com/sigstore/cosign) signature:\n\n```bash\n# Download from Releases\nwget https://github.com/zhixuli0406/DuDuClaw/releases/download/v1.21.1/duduclaw-darwin-arm64.tar.gz\n\n# Verify SHA-256 (against the .sha256 file in the release)\nshasum -a 256 -c duduclaw-darwin-arm64.tar.gz.sha256\n\n# Verify the cosign signature\ncosign verify-blob \\\n  --certificate duduclaw-darwin-arm64.tar.gz.pem \\\n  --signature duduclaw-darwin-arm64.tar.gz.sig \\\n  --certificate-identity-regexp \"https://github.com/zhixuli0406/DuDuClaw\" \\\n  --certificate-oidc-issuer \"https://token.actions.githubusercontent.com\" \\\n  duduclaw-darwin-arm64.tar.gz\n```\n\n### Supply chain transparency\n\n- **License**: Apache 2.0\n- **Maintainer**: 嘟嘟數位科技有限公司 (Taiwan-registered company, 統編 94139082)\n- **Public commit history**: github.com/zhixuli0406/DuDuClaw\n- **CI/CD**: All releases are built via GitHub Actions\n- **No telemetry**: zero phone-home calls\n- **No API key collection**: all secrets stay on your machine via an AES-256-GCM vault\n- **No privileged escalation**: runs entirely in user space\n\nTo report a vulnerability, see [SECURITY.md](SECURITY.md).\n\n---\n\n## Why DuDuClaw vs Using Native Claude / GPT / Gemini CLIs?\n\nThe native CLIs are great if you're using one LLM occasionally as a person.\nBut once you need to ship to production, you'll quickly end up rebuilding what DuDuClaw already\nprovides:\n\n| Need | Native CLIs | DuDuClaw |\n|---|---|---|\n| Multi-LLM auto-fallback | Manual restart | Built-in (4 strategies) |\n| Context preserved across LLM switches | Lost | Preserved |\n| Tools shared across LLMs | Rewrite per LLM | Write once, share |\n| Production hardening (DLQ/retry/observability) | Build yourself | Built-in |\n| Multi-channel (Telegram/LINE/Discord/...) | CLI only | 7 channels |\n| Secrets / audit / PII redaction | Build yourself | Built-in |\n\nIf you're solo using `claude` or `gemini` occasionally — stick with native.\nIf you're building **production multi-LLM Agent systems** — DuDuClaw saves you 3 months of\ninfrastructure work.\n\n---\n\n\u003e 🎉 **v1.29.0 — Cloud-tier agent/channel caps (self-host never limited)** ([Release](https://github.com/zhixuli0406/DuDuClaw/releases/tag/v1.29.0))\n\u003e\n\u003e 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.\n\u003e\n\u003e - **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\n\u003e - **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\n\u003e - `license_runtime::cap_exceeded()` pure helper + `is_self_host_deployment()` exposed to the gateway\n\n\n\nhttps://github.com/user-attachments/assets/217f56aa-8b46-4c2a-85fa-62ee68c33a4c\n\n\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ev1.9.4 → v1.28.x cumulative highlights\u003c/strong\u003e\u003c/summary\u003e\n\n- **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)\n- **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\n- **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)\n- **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\n- **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\n- **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`\n- **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\n- **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\n- **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)\n\n- **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\n- **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\n\n- **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_\u003cID\u003e` 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\n- **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_\u003cenv\u003e_\u003c64hex\u003e`, 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\n- **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\n- **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\n- **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`\n- **v1.14.0** — RFC-23 Sensitive Data Redaction: new crate `duduclaw-redaction`. Internal data (Odoo / shared wiki / file tools) is replaced with `\u003cREDACT:CATEGORY:hash8\u003e` 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\n- **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\n- **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\n- **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\n- **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\n- **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\n- **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\n\n\u003c/details\u003e\n\n---\n\n## Table of Contents\n\n- [What is DuDuClaw?](#what)\n- [Core Features](#features)\n- [Comparison](#comparison)\n- [Agent Directory Structure](#directory)\n- [Security Hooks](#security)\n- [Installation](#install)\n- [CLI Commands](#cli)\n- [Project Structure](#structure)\n- [Technical Decisions](#tech)\n- [Testing](#testing)\n- [Documentation](#docs)\n- [License](#license)\n\n---\n\n\u003ca id=\"what\"\u003e\u003c/a\u003e\n\n## What is DuDuClaw?\n\nDuDuClaw 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.\n\nIt 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.\n\nCore concepts:\n\n- **Multi-Runtime** — the `AgentRuntime` trait unifies four backends (Claude / Codex / Gemini / OpenAI-compat), `RuntimeRegistry` auto-detects, and configuration is per-agent\n- **Plumbing = DuDuClaw** — responsible for channel routing, session management, memory search, account rotation, local inference, and other infrastructure\n- **Bridge = MCP Protocol** — `duduclaw mcp-server` acts as an MCP Server, exposing channel and memory tools to the AI Runtime\n\n```\nAI Runtime (brain) — Claude CLI / Codex CLI / Gemini CLI / OpenAI-compat\n  ↕ MCP Protocol (JSON-RPC 2.0, stdin/stdout)\nDuDuClaw (plumbing)\n  ├─ Channel Router — Telegram / LINE / Discord / Slack / WhatsApp / Feishu / WebChat\n  ├─ Multi-Runtime — Claude / Codex / Gemini / OpenAI-compat auto-detection + per-agent config\n  ├─ Session Memory Stack — native --resume + Instruction Pinning + Snowball Recap + Key-Fact Accumulator\n  ├─ MCP Server — 80+ tools (messaging, memory, Agent, Skill, inference, tasks, knowledge base, ERP), per-agent registration\n  ├─ Evolution Engine — GVU² dual-loop evolution + prediction-driven + MistakeNotebook\n  ├─ Inference Engine — llama.cpp / mistral.rs / Exo P2P / llamafile / MLX / ONNX\n  ├─ Voice Pipeline — ASR (SenseVoice / Whisper) + TTS (Piper / MiniMax) + VAD (Silero)\n  ├─ Account Rotator — multi-OAuth + API Key rotation, budget tracking, health checks, Cross-Provider Failover\n  ├─ Browser Automation — 5-layer auto-routing (API Fetch → Scrape → Headless → Sandbox → Computer Use)\n  ├─ Worktree Isolation — Git worktree L0 sandbox, atomic merge, cap of 5 per Agent\n  ├─ Wiki Knowledge Layer — L0-L3 four-tier knowledge architecture + trust weighting + FTS5 + auto-injection\n  ├─ ACP/A2A Server — `duduclaw acp-server` stdio JSON-RPC 2.0, Zed/JetBrains/Neovim integration\n  └─ Web Dashboard — React 19 SPA (23 pages), embedded in the binary via rust-embed\n```\n\n---\n\n\u003ca id=\"features\"\u003e\u003c/a\u003e\n\n## Core Features\n\n### Channels \u0026 Messaging\n\n| Feature | Description |\n|------|------|\n| **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) |\n| **Per-Agent Bot** | Each Agent can have its own Bot Token, with multiple Agents running in parallel on the same platform |\n| **Channel hot-start/stop** | Adding/removing channels in the Dashboard takes effect immediately, no gateway restart needed |\n| **WebChat** | Built-in `/ws/chat` WebSocket endpoint, real-time conversation in the React frontend |\n| **Generic Webhook** | `POST /webhook/{agent_id}` + HMAC-SHA256 signature verification |\n| **Media Pipeline** | Automatic image resizing (max 1568px) + MIME detection + Vision integration |\n| **Sticker system** | LINE sticker catalog + emotion detection + Discord emoji equivalence mapping |\n\n### AI Execution \u0026 Inference\n\n| Feature | Description |\n|------|------|\n| **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 |\n| **MCP Refresh Tokens** (v1.16.0) | Long-lived credentials backed by `~/.duduclaw/mcp_tokens.db` — token form `ddc_refresh_\u003cenv\u003e_\u003c64hex\u003e`, 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_\u003cenv\u003e_\u003c32hex\u003e` 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 |\n| **Multi-Runtime** | The `AgentRuntime` trait — four backends (Claude / Codex / Gemini / OpenAI-compat), `RuntimeRegistry` auto-detection, per-agent config |\n| **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 |\n| **Three-tier confidence routing** | LocalFast → LocalStrong → CloudAPI, auto-routed via heuristic confidence scoring, with CJK-aware token estimation |\n| **InferenceManager** | Multi-mode auto-switching: Exo P2P → llamafile → Direct backend → OpenAI-compat → Cloud API, periodic health checks + automatic failover |\n| **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 (\u003e800 chars, CJK-safe); Direct API \"system_and_3\" breakpoint cache strategy |\n| **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 `\u003ctask_recap\u003e` 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%) |\n| **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 |\n| **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 |\n| **Direct API** | Bypasses the CLI to call the Anthropic Messages API directly, reaching a 95%+ cache hit rate with `cache_control: ephemeral` |\n| **Token compression** | Meta-Token (BPE-like 27-47%), LLMLingua-2 (2-5x lossy), StreamingLLM (infinite-length conversation) |\n| **Cross-Provider Failover** | `FailoverManager` health tracking, cooldown, non-retryable error detection |\n| **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 |\n| **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) |\n| **Browser automation** | 5-layer routing (API Fetch → Static Scrape → Headless Playwright → Sandbox Container → Computer Use), deny-by-default |\n\n### Voice \u0026 Multimedia\n\n| Feature | Description |\n|------|------|\n| **ASR speech recognition** | ONNX SenseVoice (local) + Whisper.cpp (local) + OpenAI Whisper API |\n| **TTS speech synthesis** | ONNX Piper (local) + MiniMax T2A |\n| **VAD voice activity detection** | ONNX Silero VAD |\n| **Discord voice channel** | Songbird integration, Discord voice conversation |\n| **LiveKit voice room** | WebRTC multi-Agent voice conferencing |\n| **ONNX embeddings** | BERT WordPiece tokenizer + ONNX Runtime vector embeddings |\n\n### Agent Orchestration \u0026 Evolution\n\n| Feature | Description |\n|------|------|\n| **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)`) |\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 |\n| **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 |\n| **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 |\n| **Prediction-driven evolution** | Active Inference + Dual Process Theory, ~90% of conversations at zero LLM cost; MetaCognition self-calibrates thresholds every 100 predictions |\n| **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 |\n| **Adaptive Depth** | MetaCognition drives GVU iteration depth (3-7 rounds), auto-adjusted based on historical success rate |\n| **Deferred GVU** | gradient accumulation + delayed retry (up to 3 deferrals, 9-21 effective iterations over a 72h span) |\n| **ConversationOutcome** | Zero-LLM conversation outcome detection (TaskType / Satisfaction / Completion), bilingual zh-TW + en |\n| **SOUL.md versioning** | 24h observation period + auto-rollback, atomic write (SHA-256 fingerprint) |\n| **`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 |\n| **`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 |\n| **Agent-as-Evaluator** | An independent Evaluator Agent (Haiku for cost control) performs adversarial verification with a structured JSON verdict |\n| **DelegationEnvelope** | Structured handoff protocol — context / constraints / task_chain / expected_output, backward-compatible with the Raw payload |\n| **TaskSpec workflow** | Multi-step task planning — dependency-aware scheduling / auto-retry (3x) / replan (up to 2x) / persistence |\n| **Orchestrator template** | 5-step planning strategy (Analyze → Decompose → Delegate → Evaluate → Synthesize) + complexity routing |\n| **Skill lifecycle** | 7-stage management — Activation → Compression → Extraction → Reconstruction → Distillation → Diagnostician → Gap Analysis |\n| **Skill auto-synthesis** | Detect repeated domain gaps → synthesize new Skills from episodic memory → sandbox trial (TTL-managed) → cross-Agent graduation |\n| **Task Board** | SQLite task management — status/priority/assignment tracking + real-time Activity Feed (WebSocket push) |\n| **Autopilot rule engine** | Automated task delegation, notification, and Skill triggering — supports task creation/status change/channel message/idle detection/Cron schedule |\n| **Shared knowledge base** | `~/.duduclaw/shared/wiki/` cross-Agent shared knowledge (SOPs, policies, product specs) + author attribution |\n| **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 |\n| **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 |\n| **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 |\n| **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 |\n| **Reminder scheduling** | One-time reminders (relative time `5m`/`2h`/`1d` or ISO 8601 absolute time), `direct` static message or `agent_callback` wake-up mode |\n\n### Reliability \u0026 Governance (added in v1.9.x)\n\n| Feature | Description |\n|------|------|\n| **`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 |\n| **`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 |\n| **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 |\n| **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 |\n| **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 |\n| **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 |\n| **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 |\n\n### Security\n\n| Feature | Description |\n|------|------|\n| **Claude Code Security Hooks** | Three-phase progressive defense — Layer 1 blacklist (\u003c50ms) → Layer 2 obfuscation detection (YELLOW+) → Layer 3 Haiku AI judgment (RED only) |\n| **Threat-level state machine** | GREEN → YELLOW → RED with auto-escalation/degradation, dropping one level after 24h with no events |\n| **SOUL.md drift detection** | Real-time SHA-256 fingerprint comparison |\n| **Prompt Injection scanning** | 6 rule categories, XML delimiter tags for injection resistance |\n| **Secret leak scanning** | 20+ patterns (Anthropic/OpenAI/AWS/GitHub/Slack/Stripe/DB URL, etc.) |\n| **Sensitive file protection** | Read/Write/Edit three-way protection of `secret.key`, `.env*`, `SOUL.md`, `CONTRACT.toml` |\n| **Behavioral contracts** | `CONTRACT.toml` defines `must_not` / `must_always` boundaries + `duduclaw test` red-team testing (9 scenarios) |\n| **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 |\n| **JSONL audit log** | Async writes, format-compatible with the Rust `AuditEvent` schema |\n| **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) |\n| **Per-Agent key isolation** | AES-256-GCM encrypted storage, keys invisible between agents |\n| **Container sandbox** | Docker / Apple Container (`--network=none`, tmpfs, read-only rootfs, 512MB limit) |\n| **Browser automation** | 5-layer routing (API Fetch → Static Scrape → Headless → Sandbox → Computer Use), deny-by-default |\n\n### Accounts \u0026 Cost\n\n| Feature | Description |\n|------|------|\n| **Dual-mode account rotation** | OAuth subscription (Pro/Team/Max) + API Key hybrid — 4 strategies (Priority/LeastCost/Failover/RoundRobin) |\n| **Health tracking** | Rate-limit cooldown (2min), billing-exhaustion cooldown (24h), token-expiry tracking (30d/7d warnings) |\n| **Cost telemetry** | SQLite token tracking, cache efficiency analysis, 200K price-cliff warning, adaptive routing (auto-switch to local when cache efficiency \u003c30%) |\n| **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 |\n| **Structured failure classification** | The `FailureReason` enum (RateLimited / Billing / Timeout / BinaryMissing / SpawnError / EmptyResponse / NoAccounts / Unknown) + category-specific zh-TW messages + `channel_failures.jsonl` audit records |\n\n### Integrations \u0026 Extensions\n\n| Feature | Description |\n|------|------|\n| **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) |\n| **Skill marketplace** | GitHub Search API live indexing + 24h local cache + security scan + Dashboard marketplace page |\n| **Prometheus metrics** | `GET /metrics` — requests, tokens, duration histogram, channel status |\n| **CronScheduler** | `cron_tasks.jsonl` + cron expressions, scheduled tasks fired automatically |\n| **ONNX embeddings** | BERT WordPiece tokenizer + ONNX Runtime vector embeddings, with semantic search support |\n| **Experiment Logger** | Trajectory recording, supporting RL/RLHF offline analysis |\n| **Memory Decay scheduling** | Background `run_decay` every 24h: low-importance + 30+ days → archive; 90+ days archived → permanent deletion |\n| **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) |\n| **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` |\n| **Partner Portal** | SQLite `PartnerStore` (`~/.duduclaw/partner.db`) + 7 RPCs (profile/stats/customers CRUD) + sales statistics |\n\n### Web Dashboard\n\n| Feature | Description |\n|------|------|\n| **Tech stack** | React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui, warm amber color scheme |\n| **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) |\n| **Reliability dashboard** | circuit breaker status / retry stats / DLQ queue depth / real-time evolution events data; the `/reliability` route, integrating the `getEvolutionEvents` / `getReliabilityStats` / `getDlqItems` APIs |\n| **Real-time logs** | BroadcastLayer tracing → WebSocket push, WS heartbeat ping/pong (server 30s / client 25s) + 60s idle close |\n| **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 |\n| **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 |\n| **Memory page evolution history** | SOUL.md version history + before/after metric diffs (positive feedback / prediction error / user corrections) + status badges (Confirmed / RolledBack / Observing) |\n| **Toast notification system** | Module-scoped event bus, max-5 queue, auto-dismiss, warm stone/amber/emerald/rose variants, respects `prefers-reduced-motion` |\n| **Org chart** | D3.js interactive Agent hierarchy visualization |\n| **Light/dark toggle** | Follows system preference, supports manual toggle |\n| **Internationalization** | zh-TW / en / ja-JP trilingual support (600+ translation keys) |\n| **Skill Market three tabs** | Marketplace / Shared Skills / My Skills three-tab architecture + Skill adoption flow |\n| **Autopilot settings** | Automation rule creation/management/monitoring + history review |\n| **Session Replay** | Conversation replay component, supports timeline view |\n\n---\n\n\u003ca id=\"comparison\"\u003e\u003c/a\u003e\n\n## Comparison\n\n| | **DuDuClaw** | **OpenClaw** | **IronClaw** | **Moltis** | **Dify** |\n|---|---|---|---|---|---|\n| Language | Rust | TypeScript | Rust | Rust | Python |\n| Channels | 7 | 25+ | 8 | 5 | 0 (API) |\n| Multi-Runtime | **4 backends (Claude/Codex/Gemini/OpenAI)** | - | - | - | Multi-LLM |\n| MCP Server | **80+ tools** | - | - | - | - |\n| Self-evolution engine | **GVU² dual-loop** | - | - | - | - |\n| Local inference | **6 backends + three-tier confidence routing** | - | - | - | - |\n| Voice (ASR/TTS) | **4 ASR + 4 TTS providers** | - | - | - | - |\n| Token compression | **3 strategies** | - | - | - | - |\n| Browser automation | **5-layer routing** | - | - | - | - |\n| Cost telemetry | **Cache efficiency analysis** | - | Basic | Basic | Basic |\n| Behavioral contracts | **CONTRACT.toml + red team** | - | WASM sandbox | - | - |\n| ERP integration | **Odoo 15 tools** | - | - | - | - |\n| Security audit | **Three-layer defense + Hooks** | CVE-2026-25253 | WASM | Basic | Medium |\n| License | **Apache 2.0 (Open Core)** | MIT | Open source | Open source | $59+/month |\n\n---\n\n\u003ca id=\"directory\"\u003e\u003c/a\u003e\n\n## Agent Directory Structure\n\nEach Agent is a folder, fully compatible with the Claude Code structure:\n\n```\n~/.duduclaw/agents/\n├── dudu/                    # Main Agent\n│   ├── .claude/             # Claude Code settings\n│   │   └── settings.local.json\n│   ├── .mcp.json            # MCP Server config (DuDuClaw platform tools + agent-specific MCP such as Playwright)\n│   │                        # auto-created/repaired at gateway startup; Claude CLI `-p` mode only reads this file\n│   ├── SOUL.md              # Persona definition (SHA-256 protected)\n│   ├── CLAUDE.md            # Claude Code guidance (includes the CLAUDE_WIKI template)\n│   ├── CONTRACT.toml        # Behavioral contract (must_not / must_always), auto-injected into the system prompt\n│   ├── agent.toml           # DuDuClaw config (model, budget, heartbeat, runtime, capabilities)\n│   ├── SKILLS/              # Skill set (can be auto-generated by the evolution engine)\n│   ├── wiki/                # Wiki knowledge base (L0-L3 tiering + trust weighting + FTS5)\n│   ├── memory/              # Daily notes + memory.db (prediction error) + key_facts table\n│   ├── tasks/               # TaskSpec workflow persistence (JSON)\n│   └── state/               # Runtime state (SQLite: sessions.pinned_instructions, etc.)\n│\n└── coder/                   # Another Agent\n    └── ...\n```\n\nUse `duduclaw migrate` to automatically convert a legacy `agent.toml` to the Claude Code-compatible format.\n\n---\n\n\u003ca id=\"security\"\u003e\u003c/a\u003e\n\n## Security Hooks\n\nDuDuClaw builds a three-phase progressive defense on top of Claude Code's Hook system:\n\n```\n                    ┌─────────────────────────────────────┐\n  SessionStart ──→  │ session-init.sh                     │  Key permission verification + environment init\n                    └─────────────────────────────────────┘\n                    ┌─────────────────────────────────────┐\n  UserPrompt   ──→  │ inject-contract.sh                  │  CONTRACT.toml rule injection\n                    └─────────────────────────────────────┘\n                    ┌─────────────────────────────────────┐\n  PreToolUse   ──→  │ bash-gate.sh (Bash)                 │  Layer 1: blacklist (\u003c50ms)\n     (Bash)         │   ├─ Layer 2: obfuscation detect (YELLOW+)    │  Layer 2: base64/eval/exfiltration\n                    │   └─ Layer 3: Haiku AI (RED only)   │  Layer 3: AI safety judgment\n                    └─────────────────────────────────────┘\n                    ┌─────────────────────────────────────┐\n  PreToolUse   ──→  │ file-protect.sh → ai-review.sh     │  Sensitive file protection + AI review\n  (Write|Edit|Read) └─────────────────────────────────────┘\n                    ┌─────────────────────────────────────┐\n  PostToolUse  ──→  │ secret-scanner.sh → audit-logger.sh │  Secret scan → async audit\n                    └─────────────────────────────────────┘\n                    ┌─────────────────────────────────────┐\n  Stop         ──→  │ threat-eval.sh                      │  Threat-level re-evaluation\n                    └─────────────────────────────────────┘\n                    ┌─────────────────────────────────────┐\n  ConfigChange ──→  │ config-guard.sh                     │  Config tampering detection\n                    └─────────────────────────────────────┘\n```\n\n### Threat-level state machine\n\n| Level | Trigger | Defense behavior |\n|------|---------|---------|\n| **GREEN** (default) | Normal operation | Layer 1 blacklist + file protection + Secret scan |\n| **YELLOW** | ≥ 2 interceptions within 1 hour | +Layer 2 obfuscation detection + external network restriction |\n| **RED** | Injection/eval attack detected | +Layer 3 Haiku AI judgment of all commands + AI file review |\n\nDegradation: automatically drops one level after 24 hours with no events (RED→YELLOW→GREEN).\n\n---\n\n\u003ca id=\"install\"\u003e\u003c/a\u003e\n\n## Installation\n\n### npm (recommended, all platforms incl. Windows)\n\n```bash\nnpm install -g duduclaw\n```\n\nAfter 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.\n\n\u003e **⚠️ If installation asks you to install Rust / MSVC Build Tools (~2GB) and compile (~1.5h), you're on the wrong path.**\n\u003e 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.\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew install zhixuli0406/tap/duduclaw\n```\n\n### One-line install\n\n**macOS / Linux:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zhixuli0406/DuDuClaw/main/scripts/install.sh | sh\n```\n\n**Windows (PowerShell):**\n\n```powershell\nirm https://raw.githubusercontent.com/zhixuli0406/DuDuClaw/main/scripts/install.ps1 | iex\n```\n\n\u003e 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.\n\n### Desktop app\n\nBesides 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):\n\n| Platform | File | Notes |\n|------|------|------|\n| macOS (Apple Silicon) | `DuDuClaw_*_aarch64.dmg` | ✅ Signed + Apple-notarized, opens with no warning |\n| macOS (Intel) | `DuDuClaw_*_x64.dmg` | ✅ Signed + Apple-notarized, opens with no warning |\n| Windows (x64) | `DuDuClaw_*_x64_en-US.msi` | ⚠️ Unsigned — see below |\n| Linux | `*_amd64.AppImage` / `*_amd64.deb` | Unsigned (not required) |\n\n\u003e 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.\n\n#### ⚠️ Windows: SmartScreen \"Unknown publisher\" warning — how to run it\n\nThe 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:\n\n1. Double-click the `.msi` → the blue SmartScreen dialog appears\n2. Click **\"More info\"**\n3. Click **\"Run anyway\"**\n\n**To avoid the warning entirely**, two options with no signing concerns:\n\n- Use the CLI instead: `npm install -g duduclaw` (full-featured, includes the dashboard)\n- 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)\n\n\u003e **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`).\n\n### Python SDK (optional library, not a CLI)\n\n\u003e **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**.\n\u003e 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.\n\n`pip install duduclaw` is **optional for core functionality** — only needed when:\n\n- You want to `import duduclaw` in your own Python code (the agents / channels / mcp / memory_eval modules).\n- You run the standalone memory-evaluation tooling (LOCOMO).\n\n\u003e **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.\n\nTo install the optional library:\n\n```bash\npip install duduclaw\n```\n\nThis command installs the following dependencies:\n\n| Package | Minimum version | Purpose |\n|------|---------|------|\n| `anthropic` | ≥ 0.40 | Direct Claude API calls from your own Python code |\n| `httpx` | ≥ 0.27 | Async HTTP client (account rotation, health checks) |\n| `pyyaml` | ≥ 6.0 | Config file parsing |\n\n#### macOS (Homebrew Python) / other externally-managed environments\n\nIf 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:\n\n```bash\n# venv\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install --upgrade duduclaw\n\n# or use uv (already adopted by this project, much faster)\nuv venv \u0026\u0026 uv pip install --upgrade duduclaw\n```\n\nVerify the installed version:\n\n```python\nimport duduclaw\nprint(duduclaw.__version__)   # reflects the actually installed PyPI version\n```\n\n\u003e `__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.\n\nFor development environments, additionally install:\n\n```bash\npip install duduclaw[dev]\n# Includes: pytest\u003e=8, pytest-asyncio\u003e=0.24, ruff\u003e=0.8\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/zhixuli0406/DuDuClaw.git\ncd DuDuClaw\n\n# (Optional) only needed for the importable Python library / memory-eval tooling; the core build does not require it\n# pip install duduclaw\n\n# Build the Dashboard\ncd web \u0026\u0026 npm ci --legacy-peer-deps \u0026\u0026 npm run build \u0026\u0026 cd ..\n\n# Build the Rust binary (with Dashboard)\ncargo build --release -p duduclaw-cli -p duduclaw-gateway --features duduclaw-gateway/dashboard\n\n# First-time setup\n./target/release/duduclaw onboard\n\n# Start\n./target/release/duduclaw run\n```\n\n\u003e **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)\n\n---\n\n\u003ca id=\"cli\"\u003e\u003c/a\u003e\n\n## CLI Commands\n\n```\nduduclaw onboard             # Interactive first-time setup\nduduclaw run                 # One-click start (gateway + channels + heartbeat + cron + dispatcher)\nduduclaw migrate             # Convert agent.toml to Claude Code format\nduduclaw mcp-server          # Start the MCP Server (for the AI Runtime, stdio JSON-RPC 2.0)\nduduclaw http-server         # Start the MCP HTTP/SSE Transport (Bearer auth, default 127.0.0.1:8765)\nduduclaw acp-server          # Start the ACP/A2A Server (IDE integration: Zed/JetBrains/Neovim)\nduduclaw gateway             # Start only the WebSocket gateway server\n\nduduclaw agent               # CLI interactive conversation\nduduclaw agent list          # List all Agents\nduduclaw agent create        # Create a new Agent (industry template optional)\nduduclaw agent inspect       # View Agent details\nduduclaw agent pause         # Pause an Agent\nduduclaw agent resume        # Resume an Agent\nduduclaw agent edit          # Edit Agent settings\nduduclaw agent remove        # Remove an Agent\n\nduduclaw test \u003cagent\u003e        # Red-team security test (9 built-in scenarios + JSON report)\nduduclaw status              # System health snapshot\nduduclaw doctor              # Health diagnostics\nduduclaw wizard              # Interactive industry-template setup\nduduclaw evolution finalize  # One-shot recovery of overdue SOUL.md observation windows (--dry-run / --agent \u003cid\u003e)\n\nduduclaw rl export           # Export RL trajectory (~/.duduclaw/rl_trajectories.jsonl)\nduduclaw rl stats            # Per-Agent trajectory statistics\nduduclaw rl reward           # Compute composite reward (outcome×0.7 + efficiency×0.2 + overlong×0.1)\n\nduduclaw service install     # Install as a system service\nduduclaw service start/stop  # Start/stop the system service\nduduclaw service status      # Service status\nduduclaw service logs        # Service logs\nduduclaw service uninstall   # Remove the system service\n\nduduclaw license activate    # Activate license\nduduclaw license status      # License status\nduduclaw license verify      # Verify license\nduduclaw update              # Check for and install updates\nduduclaw version             # Version info\n```\n\n---\n\n\u003ca id=\"structure\"\u003e\u003c/a\u003e\n\n## Project Structure\n\n```\nDuDuClaw/\n├── crates/                         # Rust crates (20)\n│   ├── duduclaw-core/              # Shared types, traits (Channel, MemoryEngine), error definitions\n│   ├── duduclaw-agent/             # Agent registry, heartbeat, budget, contract, skill loader/registry\n│   ├── duduclaw-auth/              # Multi-user auth (Argon2 passwords, JWT, ACL role permissions)\n│   ├── duduclaw-security/          # AES-256-GCM, SOUL guard, input guard, audit, key vault\n│   ├── duduclaw-container/         # Docker / Apple Container / WSL2 sandbox execution\n│   ├── duduclaw-memory/            # SQLite + FTS5 full-text search + vector embeddings + eval batch query API\n│   ├── duduclaw-inference/         # Local inference engine (llama.cpp / mistral.rs / ONNX / Exo / llamafile)\n│   ├── duduclaw-gateway/           # Axum server, 7 channels, session, GVU², prediction, cron, dispatcher, LLM fallback, evolution events, PTY pool integration\n│   ├── duduclaw-bus/               # tokio broadcast + mpsc message routing\n│   ├── duduclaw-bridge/            # PyO3 Rust↔Python bridge layer\n│   ├── duduclaw-odoo/              # Odoo ERP middleware (JSON-RPC, CE/EE, 15 MCP tools)\n│   ├── duduclaw-cli/               # clap CLI entry + MCP server (stdio + HTTP/SSE) + migrate + test\n│   ├── duduclaw-dashboard/         # rust-embed embedded React SPA\n│   ├── duduclaw-desktop/           # Desktop wrapper (macOS/Windows/Linux)\n│   ├── duduclaw-durability/        # Durability framework (idempotency / retry / circuit breaker / checkpoint / DLQ) — added in v1.9.4\n│   ├── duduclaw-governance/        # PolicyRegistry / quota_manager / error_codes / audit / approval — added in v1.9.4\n│   ├── duduclaw-identity/          # IdentityProvider trait + Wiki/Notion/Chained three implementations — added in v1.11.0\n│   ├── duduclaw-redaction/         # Source-aware redaction + reversible vault (AES-256-GCM) + 5 profiles + JSONL audit — added in v1.14.0\n│   ├── duduclaw-cli-runtime/       # Cross-platform PTY pool runtime (portable-pty / sentinel-framed) — added in v1.15.0\n│   └── duduclaw-cli-worker/        # Standalone PTY pool worker subprocess (localhost JSON-RPC + Bearer token) — added in v1.15.0\n│\n├── python/duduclaw/                # Python extension layer\n│   ├── channels/                   # LINE / Telegram / Discord channel plugins\n│   ├── sdk/                        # Claude Code SDK chat + multi-account rotation\n│   ├── evolution/                  # Skill Vetter security scan\n│   ├── tools/                      # Agent dynamic management tools\n│   ├── agents/                     # capability manifest + capability-based router + memory_resolver (v1.9.4)\n│   ├── mcp/                        # MCP API Key auth (with key masking) + memory tools (store/read/search/namespace/quota)\n│   └── memory_eval/                # LOCOMO memory evaluation (retrieval/retention + cron + 200 golden QA) — added in v1.9.4\n│\n├── npm/                            # npm published packages\n│   ├── duduclaw/                   # Main package (platform-agnostic wrapper + postinstall binary download)\n│   ├── darwin-arm64/               # macOS Apple Silicon precompiled binary\n│   ├── darwin-x64/                 # macOS Intel precompiled binary\n│   ├── linux-x64/                  # Linux x86-64 precompiled binary\n│   ├── linux-arm64/                # Linux ARM64 precompiled binary\n│   └── win32-x64/                  # Windows x64 precompiled binary\n│\n├── web/                            # React Dashboard\n│   └── src/\n│       ├── components/             # UI components (OrgChart, ApprovalModal, SessionReplay)\n│       ├── pages/                  # 24 pages (including ReliabilityPage added in v1.9.4)\n│       ├── stores/                 # Zustand state management (8 stores)\n│       ├── lib/                    # API client (WebSocket JSON-RPC + evolution events / reliability HTTP)\n│       └── i18n/                   # zh-TW / en / ja-JP\n│\n├── templates/                      # Industry templates + Agent role templates\n│   ├── restaurant/                 # Restaurant (customer service, reservations, FAQ, proactive push)\n│   ├── manufacturing/              # Manufacturing (equipment monitoring, SOP, anomaly alerts)\n│   ├── trading/                    # Trading (quotes, orders, inventory, price lists)\n│   ├── evaluator/                  # Evaluator Agent (adversarial verification)\n│   ├── orchestrator/               # Orchestrator Agent (task orchestration)\n│   └── wiki/                       # Wiki knowledge base template\n│\n├── .claude/                        # Claude Code Hook security system\n│   ├── settings.local.json         # Hook config (6 events × 10 scripts)\n│   └── hooks/                      # Three-phase progressive defense scripts\n│\n├── docs/                           # Public documentation\n│   ├── spec/                       # Format specs (SOUL.md / CONTRACT.toml)\n│   ├── api/                        # WebSocket RPC + OpenAPI spec\n│   ├── guides/                     # Development guides (custom MCP tools, etc.)\n│   └── *.md                        # Architecture, deployment, evolution engine, etc.\n│\n├── ARCHITECTURE.md                 # Complete architecture design document\n└── CLAUDE.md                       # AI collaboration design context\n```\n\n---\n\n\u003ca id=\"tech\"\u003e\u003c/a\u003e\n\n## Technical Decisions\n\n| Item | Choice | Rationale |\n|------|------|------|\n| AI conversation | **Multi-Runtime (Claude / Codex / Gemini CLI)** | Not tied to a single provider; auto-detection + per-agent config |\n| Core language | **Rust** | Memory safety, high performance, single-binary deployment |\n| Extension language | **Python (PyO3)** | Claude Code SDK integration, channel-plugin flexibility |\n| Frontend framework | **React 19 + TypeScript** | Real-time data updates, mature ecosystem |\n| UI style | **shadcn/ui + Tailwind CSS 4** | Warm, customizable, good performance |\n| Database | **SQLite + FTS5** | Zero dependency, embedded, full-text search |\n| Tool protocol | **MCP (Model Context Protocol)** | Native Claude Code support, stdin/stdout JSON-RPC |\n| Local inference | **ONNX Runtime + llama.cpp** | Cross-platform, Metal/CUDA/Vulkan GPU acceleration |\n| Speech recognition | **SenseVoice + Whisper.cpp** | Multilingual, local offline, zero API cost |\n| Real-time communication | **WebRTC (LiveKit)** | Low-latency voice, multi-party conferencing |\n\n---\n\n\u003ca id=\"testing\"\u003e\u003c/a\u003e\n\n## Testing\n\n```bash\n# Rust tests\ncargo test --workspace --exclude duduclaw-bridge\n\n# Python tests\npip install pytest pytest-asyncio ruff\nruff check python/\npytest tests/python/ -v\n\n# Frontend type checking\ncd web \u0026\u0026 npx tsc --noEmit\n```\n\n---\n\n\u003ca id=\"docs\"\u003e\u003c/a\u003e\n\n## Documentation\n\n- [ARCHITECTURE.md](ARCHITECTURE.md) — Complete system architecture design\n- [CLAUDE.md](CLAUDE.md) — AI collaboration design context and principles\n- [CHANGELOG.md](CHANGELOG.md) — Version change log\n- [docs/features/README.md](docs/features/README.md) — Detailed feature breakdown (19 articles, with zh-TW / ja-JP translations)\n- [docs/features/feature-inventory.md](docs/features/feature-inventory.md) — Complete feature inventory\n- [docs/spec/soul-md-spec.md](docs/spec/soul-md-spec.md) — SOUL.md format spec v1.0\n- [docs/spec/contract-toml-spec.md](docs/spec/contract-toml-spec.md) — CONTRACT.toml format spec v1.0\n- [docs/api/README.md](docs/api/README.md) — WebSocket RPC protocol + JSON-RPC 2.0 interface\n- [docs/architecture/evolution-engine.md](docs/architecture/evolution-engine.md) — Evolution Engine v2 design document\n- [docs/guides/deployment-guide.md](docs/guides/deployment-guide.md) — Production deployment guide\n- [docs/guides/development-guide.md](docs/guides/development-guide.md) — Developer setup and Agent development\n- [docs/guides/custom-mcp-tool.md](docs/guides/custom-mcp-tool.md) — Custom MCP tool tutorial\n\n---\n\n\u003ca id=\"license\"\u003e\u003c/a\u003e\n\n## License\n\n**Open Core model** — the core code is licensed under [Apache License 2.0](LICENSE), completely free to use, modify, and distribute.\n\nCommercial value-add modules (the `commercial/` directory) are closed-source and paid, including: industry templates, evolution parameter sets, the enterprise dashboard, and license verification.\n\nSee [LICENSING.md](LICENSING.md) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  🐾 Built with louis.li\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhixuli0406%2Fduduclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhixuli0406%2Fduduclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhixuli0406%2Fduduclaw/lists"}