{"id":45079333,"url":"https://github.com/ucsandman/dashclaw","last_synced_at":"2026-07-06T05:00:33.226Z","repository":{"id":338076598,"uuid":"1152532642","full_name":"ucsandman/DashClaw","owner":"ucsandman","description":"🛡️The governance runtime for AI agents. Intercept actions, enforce guard policies, require approvals, and produce audit-ready decision trails.","archived":false,"fork":false,"pushed_at":"2026-07-02T02:14:18.000Z","size":91755,"stargazers_count":279,"open_issues_count":7,"forks_count":49,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-07-02T02:25:10.288Z","etag":null,"topics":["agent-framework","agent-governance","agent-runtime","ai-agents","ai-governance","ai-infrastructure","ai-ops","autogen","claude-code","crew-ai","decision-engine","developer-tools","hermes","langchain","mcp","mcp-server","model-context-protocol","openclaw"],"latest_commit_sha":null,"homepage":"https://www.dashclaw.io/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ucsandman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"AUDIT_FINDINGS.md","citation":null,"codeowners":null,"security":".github/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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-08T02:34:15.000Z","updated_at":"2026-07-02T02:14:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"d03b364a-56aa-48a8-af02-cf91a2430532","html_url":"https://github.com/ucsandman/DashClaw","commit_stats":null,"previous_names":["ucsandman/dashclaw"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ucsandman/DashClaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucsandman%2FDashClaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucsandman%2FDashClaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucsandman%2FDashClaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucsandman%2FDashClaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ucsandman","download_url":"https://codeload.github.com/ucsandman/DashClaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucsandman%2FDashClaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35178403,"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-06T02:00:07.184Z","response_time":106,"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-framework","agent-governance","agent-runtime","ai-agents","ai-governance","ai-infrastructure","ai-ops","autogen","claude-code","crew-ai","decision-engine","developer-tools","hermes","langchain","mcp","mcp-server","model-context-protocol","openclaw"],"created_at":"2026-02-19T14:12:48.696Z","updated_at":"2026-07-06T05:00:33.199Z","avatar_url":"https://github.com/ucsandman.png","language":"TypeScript","funding_links":[],"categories":["🛡️ Security \u0026 Safety"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"public/images/logo-circular.png\" alt=\"DashClaw\" width=\"220\" /\u003e\n\n  \u003ch1\u003eDashClaw\u003c/h1\u003e\n\n  \u003cp\u003e\u003cstrong\u003eGovern AI agents before they act.\u003c/strong\u003e\u003c/p\u003e\n\n  \u003cp\u003e\n    DashClaw is the governance layer for AI agents that touch real systems.\n    It sits between agents and the world, evaluates policy on every risky action,\n    routes human approval where it is required, records verifiable evidence,\n    and tracks terminal outcomes so a retried agent never silently double-executes.\n  \u003c/p\u003e\n\n  \u003cp\u003e\u003csub\u003ePlugs into the agents you already run: Claude Code, Codex, Hermes Agent, OpenClaw, Claude Desktop, and Claude Managed Agents. Framework integrations for LangChain, CrewAI, AutoGen, LangGraph, and OpenAI Agents SDK. Any other runtime over MCP, the Node/Python SDK, or direct REST.\u003c/sub\u003e\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003cstrong\u003e\u003ca href=\"https://hosted.dashclaw.io/connect\"\u003eTry it now →\u003c/a\u003e\u003c/strong\u003e mint a free trial workspace in your browser and send your first governed action. No install, no deploy.\n  \u003c/p\u003e\n\n  \u003cp\u003e\u003csub\u003e\u003cstrong\u003eThis project is maintained by an AI\u003c/strong\u003e — in public, under a human-held charter. \u003ca href=\"MAINTAINER.md\"\u003eMAINTAINER.md\u003c/a\u003e holds the five invariants the maintainer cannot change; every decision is on the record in the \u003ca href=\"docs/maintainer-log.md\"\u003emaintainer log\u003c/a\u003e.\u003c/sub\u003e\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"#deploy\"\u003e\u003cimg alt=\"Deploy\" src=\"https://img.shields.io/badge/Deploy-Vercel%20%2B%20Neon-orange?style=flat-square\" /\u003e\u003c/a\u003e\n    \u003ca href=\"#10-second-demo\"\u003e\u003cimg alt=\"Try the demo\" src=\"https://img.shields.io/badge/Demo-npx%20dashclaw--demo-blue?style=flat-square\" /\u003e\u003c/a\u003e\n    \u003ca href=\"#choose-your-integration-path\"\u003e\u003cimg alt=\"Connect an agent\" src=\"https://img.shields.io/badge/Connect-MCP%20%7C%20SDK%20%7C%20Hooks-zinc?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://dashclaw.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/website-dashclaw.io-orange?style=flat-square\" alt=\"Website\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://dashclaw.io/docs\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-SDK%20%26%20API-blue?style=flat-square\" alt=\"Docs\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ucsandman/DashClaw/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/ucsandman/DashClaw?style=flat-square\u0026color=yellow\" alt=\"GitHub stars\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ucsandman/DashClaw/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" alt=\"License\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/dashclaw\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/dashclaw?style=flat-square\u0026color=orange\" alt=\"npm\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/dashclaw/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/dashclaw?style=flat-square\u0026color=orange\" alt=\"PyPI\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\n  \u003cbr /\u003e\n\n  \u003cimg src=\"docs/media/governance-loop.gif\" alt=\"The governance loop: an agent declares intent, guard evaluates policy and scores risk, a human approves, and a replayable decision record is written\" width=\"780\" /\u003e\n\n  \u003cp\u003e\u003csub\u003eThe loop, end to end: \u003cstrong\u003eintent → guard → approve → record\u003c/strong\u003e. Rendered with \u003ca href=\"https://github.com/remotion-dev/remotion\"\u003eRemotion\u003c/a\u003e from \u003ca href=\"media/remotion/\"\u003emedia/remotion/\u003c/a\u003e.\u003c/sub\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n## 60-second proof path\n\n1. Read the loop: DashClaw intercepts risky agent intent, enforces policy, records the decision, routes approval when required, and verifies the final outcome. Where the *block* is mechanical vs honored by the agent depends on the surface — hooks and server-executed capabilities halt the action itself; SDK/MCP/chat callers honor the decision. The per-surface table is [`docs/architecture/enforcement-boundary.md`](./docs/architecture/enforcement-boundary.md).\n2. Try it hosted, no install: open [hosted.dashclaw.io/connect](https://hosted.dashclaw.io/connect), mint a trial workspace, and send your first governed action straight from the browser. Expected proof: the action lands in your decisions ledger, replayable.\n3. Or run the local demo: `npx dashclaw-demo` (needs Docker running). Expected proof: a simulated high-risk deployment is blocked and opens Decision Replay.\n4. Self-host the runtime from the deploy guide, then run `npm run doctor` locally or `dashclaw doctor` against the hosted URL. Expected proof: the doctor command exits 0 or names the blocking setup item.\n5. Connect one agent with `DASHCLAW_BASE_URL` and `DASHCLAW_API_KEY`. Expected proof: one action appears in `/decisions`, any held action appears in `/approvals`, and `/api/setup/live-proof` can capture setup evidence for onboarding or CI.\n\n## What DashClaw does\n\n| | |\n|---|---|\n| **Intercept** | Risky agent actions are evaluated before they execute. Block, warn, or hold for approval, by policy — halted mechanically on hook/gateway surfaces (Claude Code, Codex, Hermes, OpenClaw) and for capabilities DashClaw executes; honored cooperatively by SDK/MCP/chat callers ([enforcement boundary](./docs/architecture/enforcement-boundary.md)). |\n| **Verify identity** | Agents authenticate with JWKS-verified OIDC bearer tokens (EdDSA / RSA / ECDSA). Replay protection rejects reused tokens; optional action binding scopes a token to one intended call. Cryptographic attribution, not self-assertion. |\n| **Enforce** | Declarative policies (risk thresholds, deploy gates, capability access rules, semantic checks) evaluate every reported action; a `block` decision is never downgraded. |\n| **Approve** | Pending approvals route to a dashboard queue, the CLI inbox, a mobile PWA, Telegram, or Discord, with one-tap allow or deny. |\n| **Record** | Every action becomes a replayable decision record: declared goal, reasoning, risk score, matched policies, assumptions, evidence. |\n| **Finalize** | Terminal outcomes are one-shot and durable. Lost confirmations are swept and surfaced, so retries do not double-execute. |\n| **Govern external systems** | The capability registry wraps real HTTP APIs with per-agent access rules, rate limits, and audit. Workflows compose these into multi-step governed runs. |\n| **Improve** | Code Sessions ingests Claude Code transcripts (Stop-hook live or JSONL backfill), prices the spend, surfaces optimizer signals (stuck loops, cache crater, context gaps), and distills sessions into an Optimal Files bundle — root CLAUDE.md, path-scoped rules, hooks, and skill packs — applied locally via `dashclaw code apply`. |\n\n---\n\n## The control plane, running\n\nReal screenshots from the maintainer's own live instance — the fleet that builds DashClaw, governed by DashClaw. Dark instrument panel, orange only where attention is required.\n\n**The decisions ledger.** Every governed action lands here with its risk score, matched policies, signature state, and terminal outcome. 77,000+ decisions on this dogfood instance; each one replayable.\n\n\u003cimg src=\"docs/media/shot-decisions.png\" alt=\"Decisions Ledger: a global stream of governed agent actions with risk scores, governance chips, completed outcomes, success rate, and tracked spend\" width=\"100%\" /\u003e\n\n**Mission Control.** Fleet posture, the intervention queue, and a live ledger of governed events on one calm screen. Repeated signal occurrences collapse into one row; dismissing it clears them all.\n\n\u003cimg src=\"docs/media/shot-mission-control.png\" alt=\"Mission Control: fleet posture summary, governance categories, runtime stats, and a live stream of governed events for 58 agents\" width=\"100%\" /\u003e\n\n**Spend and posture, measured.** Analytics prices every action and breaks enforcement down by agent and type. Governance posture is one gaming-resistant score: a policy only counts when replaying real traffic proves it fires, and drafting a policy never raises the number.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/media/shot-analytics.png\" alt=\"Analytics: total cost, action volume, cost trend, per-agent spend, and policy enforcement counts (blocked, approvals, warnings)\" /\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/media/shot-posture.png\" alt=\"Governance posture: a 0-100 risk-weighted score with a prioritized remediation queue of not-fully-governed action types\" /\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003csub\u003e\u003ccode\u003e/analytics\u003c/code\u003e · cost, volume, enforcement\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003csub\u003e\u003ccode\u003e/posture\u003c/code\u003e · proven coverage, not vibes\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Choose your integration path\n\nDashClaw meets agents where they already are. Every path lands on the same governance primitives, audit ledger, and approval queue — pick the one closest to how your agent already runs.\n\n### Coverage at a glance\n\n| If your agent is… | Use this path | Install |\n|---|---|---|\n| Claude Code | Plugin + hooks | `npm i -g @dashclaw/cli \u0026\u0026 dashclaw install claude` |\n| Codex | Plugin | `dashclaw install codex --project \u003cpath\u003e` |\n| Hermes Agent | Plugin (8 lifecycle hooks) | `bash scripts/install-hermes-plugin.sh` |\n| OpenClaw | OpenClaw plugin | `npm install @dashclaw/openclaw-plugin` |\n| Claude Desktop (chat, web, Cowork) | Custom connector (OAuth, no install) | Settings → Connectors → paste `https://\u003cinstance\u003e/api/mcp` |\n| Any stdio MCP host | MCP server (stdio) | `npx @dashclaw/mcp-server` |\n| Claude Managed Agents | MCP server (Streamable HTTP) | Point at `/api/mcp` |\n| LangChain | Python SDK callback handler | `pip install dashclaw` |\n| CrewAI | Python SDK task callback / agent wrapper | `pip install dashclaw` |\n| AutoGen | Python SDK instrumentation | `pip install dashclaw` |\n| LangGraph, OpenAI Agents SDK | Node or Python SDK | `npm install dashclaw` |\n| Custom / framework-less | Node or Python SDK | `npm install dashclaw` |\n| Anything HTTP | REST API + webhooks | [OpenAPI spec](./docs/openapi/critical-stable.openapi.json) |\n\nWorking end-to-end examples for each runtime live in [`examples/`](./examples/) — `anthropic-governed-agent`, `autogen-governed`, `claude-code-review-agent`, `codex-review-agent`, `crewai-governed`, `langgraph-governed`, `managed-agent-governed`, `managed-agent-mcp`, `openai-agents-governed`, and more.\n\n### 1. Coding-agent plugins (Claude Code, Codex, Hermes Agent)\n\nOne plugin source, three ecosystems. Distributed via [`plugins/dashclaw/`](./plugins/dashclaw/). Each manifest ships the MCP server config, the `dashclaw-governance` protocol skill, the `dashclaw-platform-intelligence` reference skill, and a distinct `agent_id` so Mission Control separates sessions per host.\n\n```bash\n# Claude Code — no clone needed: the CLI downloads the hooks bundle from your\n# instance, wires ~/.claude/settings.json, and defaults to observe mode\nnpm i -g @dashclaw/cli\ndashclaw install claude            # prompts for endpoint + API key\ndashclaw install claude --trial    # browser signup on hosted.dashclaw.io (default), paste the key\n\n# Codex — installer wires manifest, hooks, and AGENTS.md governance protocol\nnode cli/bin/dashclaw.js install codex --project /path/to/your/project\n\n# Hermes Agent — 8 lifecycle hooks (pre/post tool, pre/post LLM, on-session\n# start/end, secret redaction, subagent_stop ROI tracking)\nbash scripts/install-hermes-plugin.sh        # macOS / Linux\npowershell -File scripts/install-hermes-plugin.ps1   # Windows\n```\n\nFor Claude Code specifically, `dashclaw install claude` governs Bash, Edit, Write, MultiEdit, sub-agent spawns, and every `mcp__*` tool call with semantic classification, risk scoring, and per-turn token capture — no SDK calls in your agent code, no repo clone. Identity is per-harness (the installer writes an explicit `--agent-id` onto each hook command, so Claude Code, Codex, and Hermes on one machine report as three distinct agents), and sub-agents appear as their own fleet identities (`claude-code:explore`) grouped under their parent in `/agents`, inheriting its permissions, targeted policies, and spend budgets. It starts in observe mode (decisions logged, nothing blocked); flip to enforce by setting `DASHCLAW_HOOK_MODE=enforce` in `~/.dashclaw/claude-hooks/.env`. Working from a checkout instead, `npm run hooks:install` does the same wiring. Full details in [`hooks/README.md`](hooks/README.md).\n\n**Verify it fires:** pipe a fake tool call through the hook — a clean exit (and a guard evaluation when DashClaw is reachable) confirms the wiring. Use `python3` if your system has no `python` on PATH; the installer picks the right one automatically.\n\n```bash\necho '{\"tool_name\":\"Bash\",\"tool_input\":{\"command\":\"echo hello\"},\"tool_use_id\":\"test_001\",\"session_id\":\"smoke\"}' | python .claude/hooks/dashclaw_pretool.py\n```\n\n### 2. MCP server (zero code, any MCP host)\n\n[`@dashclaw/mcp-server`](./mcp-server) exposes **33 governance MCP tools** across 12 groups — core governance, optimal files, session continuity, credential hygiene, skill safety, open loops, learning + retrospection, agent inbox, agent identity, behavior learning, governance posture, work orders — plus 6 read-only resources (`dashclaw://policies`, `dashclaw://capabilities`, `dashclaw://agent/{agent_id}/history`, `dashclaw://status`, `dashclaw://code-sessions/projects`, `dashclaw://code-sessions/sessions/{session_id}`).\n\nAs of v2.0.0 the local stdio server also carries **governed execution**: provider tools for GitHub, Vercel, Neon, Stripe and ten more (each registering only when its credential env var is present), and stateful **launch plans** (`create_launch_plan` / `get_launch_status` / `preflight_launch` / `verify_launch`) that track the launch tail with reality-checked, never self-reported completion — every step through the same guard/policy/approval path. See [`mcp-server/README.md`](./mcp-server/README.md) and [`mcp-server/docs/launch-plans.md`](./mcp-server/docs/launch-plans.md).\n\n**Stdio (Claude Code, any stdio MCP client — not Claude Desktop chat, whose bundled Node crashes local MCP servers; Desktop uses the OAuth connector below):**\n\n```json\n{\n  \"mcpServers\": {\n    \"dashclaw\": {\n      \"command\": \"npx\",\n      \"args\": [\"@dashclaw/mcp-server\"],\n      \"env\": {\n        \"DASHCLAW_URL\": \"https://your-dashclaw.vercel.app\",\n        \"DASHCLAW_API_KEY\": \"oc_live_xxx\"\n      }\n    }\n  }\n}\n```\n\n**Streamable HTTP (Claude Managed Agents, any remote MCP client):** every DashClaw instance serves MCP at `/api/mcp` — no npm package, no client install. For Claude Desktop / claude.ai, add it as a **custom connector** (Settings → Connectors → paste `https://\u003cinstance\u003e/api/mcp`): OAuth auto-discovers — no key in the UI — and tool calls attribute to the `claude-desktop` agent identity. Full walkthrough: [`docs/CLAUDE-DESKTOP-PLUGIN.md`](./docs/CLAUDE-DESKTOP-PLUGIN.md).\n\n```python\nagent = client.beta.agents.create(\n    name=\"Governed Agent\",\n    model=\"claude-sonnet-4-6\",\n    tools=[{\"type\": \"agent_toolset_20260401\"}],\n    mcp_servers=[{\n        \"type\": \"url\",\n        \"url\": \"https://your-dashclaw.vercel.app/api/mcp\",\n        \"headers\": {\"x-api-key\": \"oc_live_xxx\"},\n        \"name\": \"dashclaw\"\n    }],\n)\n```\n\n### 3. Node and Python SDKs — including framework integrations\n\nFor custom agents, frameworks, and anywhere you want explicit control over what gets governed.\n\n```bash\nnpm install dashclaw     # Node 18+\npip install dashclaw     # Python 3.7+\n```\n\n149-method canonical Node surface: core governance, durable execution finality, scoring profiles, learning analytics, messaging, handoffs, security scanning, sessions, agent reputation, agent registry, x402 spend governance, work orders, drift detection, and the execution-studio domains (workflow templates, model strategies, knowledge collections, capability runtime). The Python SDK exposes 234 methods including ready-made framework integrations:\n\n```python\n# LangChain — auto-log LLM calls, tool use, and costs\nfrom dashclaw.integrations.langchain import DashClawCallbackHandler\nagent.run(\"Hello world\", callbacks=[DashClawCallbackHandler(claw)])\n\n# CrewAI — per-task callback or agent-level instrumentation\nfrom dashclaw.integrations.crewai import DashClawCrewIntegration\nintegration = DashClawCrewIntegration(claw)\nanalyst = integration.instrument_agent(analyst)\n\n# AutoGen — multi-agent conversation monitoring\nfrom dashclaw.integrations.autogen import DashClawAutoGenIntegration\nDashClawAutoGenIntegration(claw).instrument_agent(assistant)\n```\n\nFull method catalogues: [`sdk/README.md`](./sdk/README.md) (Node, camelCase), [`sdk-python/README.md`](./sdk-python/README.md) (Python, snake_case). The 4-step governance loop is in the [Quick start](#quick-start) below.\n\n### 4. OpenClaw plugin\n\nFor agents built on [OpenClaw](https://github.com/openclaw), [`@dashclaw/openclaw-plugin`](./packages/openclaw-plugin) wires governance into the lifecycle directly.\n\n```bash\nnpm install @dashclaw/openclaw-plugin\n```\n\nIt intercepts every tool-use call (`before_tool_call`, `llm_output`, `after_tool_call`, `agent_end`), calls guard / record / waitForApproval automatically, and ships a `HOOK.md` the `openclaw` CLI installs. Tool-classification vocabulary aligns with DashClaw guard action types so policies behave consistently across plugin, hook, and SDK paths.\n\n### 5. Direct REST API and webhooks\n\nEvery governance primitive is reachable as HTTP. The stable contract is pinned in [`docs/openapi/critical-stable.openapi.json`](./docs/openapi/critical-stable.openapi.json); the full inventory (**335 routes**: 57 stable, 24 beta, 254 experimental) is at [`docs/api-inventory.md`](./docs/api-inventory.md). Webhook events include `signal.detected`, `decision.created`, `action.created`, `lost_confirmation`, and the rest of the catalog — configurable per org.\n\n### 6. Work Orders — task-grade contracts + receipts\n\nWork Orders turn an agent call into a contract: a typed input/output schema, a budget ceiling, and a self-verifying receipt. A caller submits an order against a registered type (validated, guard-gated, queued); any agent with an API key claims and completes it; the server validates the output, builds a SHA-256-hashed receipt (cost, timestamps, output hash, governance trail), and writes an audit record. DashClaw stays the control plane — execution is external workers via `claim`/`complete`, so there's no LLM key and no cron. Page at `/work-orders`, API at `/api/work-orders`, 8 SDK methods each (Node + Python), 2 MCP tools, and a ~75-line reference worker in [`examples/work-order-worker/`](./examples/work-order-worker/).\n\n### 7. Skills — governance protocol + live platform reference\n\nTwo drop-in skills, both available as zip bundles or source directories in [`public/downloads/`](./public/downloads/) and auto-bundled into the coding-agent plugins:\n\n- [`dashclaw-governance`](./public/downloads/dashclaw-governance/) — governance protocol skill. Teaches agents the decision tree (allow / warn / block / require_approval), action recording, approval-wait protocol, session lifecycle, plus six new sections for handoffs, secret hygiene, skill safety, action-scoped open loops, learning, and in-session retrospection.\n- [`dashclaw-platform-intelligence`](./public/downloads/dashclaw-platform-intelligence/) — live API reference, env var contract, and troubleshooting playbook with progressive disclosure. Regenerated from the codebase on every release so it never drifts from the running runtime.\n\n```bash\ncp -r public/downloads/dashclaw-governance .claude/skills/\ncp -r public/downloads/dashclaw-platform-intelligence .claude/skills/\n```\n\nOr grab the zips from [dashclaw.io/downloads](https://dashclaw.io/downloads). The platform-intelligence skill is also published on [ClawHub](https://clawhub.ai/@dashclaw).\n\n---\n\n## Quick start\n\n### 10-second demo\n\n```bash\nnpx dashclaw-demo\n```\n\nPulls the demo image and runs it locally (requires Docker), fires a simulated high-risk deployment, lets DashClaw block it, and opens Decision Replay in your browser. No accounts, no config. No Docker? The [hosted trial](https://hosted.dashclaw.io/connect) needs neither.\n\n### Real agent in 8 minutes (SDK path)\n\n```bash\nnpm install dashclaw   # or: pip install dashclaw\n```\n\n```javascript\nimport { DashClaw, GuardBlockedError, ApprovalDeniedError } from 'dashclaw';\n\nconst claw = new DashClaw({\n  baseUrl: process.env.DASHCLAW_BASE_URL,\n  apiKey: process.env.DASHCLAW_API_KEY,\n  agentId: 'my-agent',\n});\n\n// 1. Guard — attach the real act and the server classifies from evidence,\n//    not your declaration (evidence can only raise the risk, never lower it)\nconst decision = await claw.guard({\n  action_type: 'deploy',\n  risk_score: 80,\n  act: { kind: 'shell', command: 'vercel deploy --prod' },\n});\n\n// 2. Record\nconst action = await claw.createAction({\n  action_type: 'deploy',\n  declared_goal: 'Ship release 2.13.4 to production',\n});\n\n// 3. Verify reasoning basis\nawait claw.recordAssumption({\n  action_id: action.action_id,\n  assumption: 'Tests passed on the candidate commit',\n});\n\n// 4. Outcome (durable, retry-safe)\ntry {\n  // ...do the real work...\n  await claw.reportActionSuccess(action.action_id, 'Deployed 2.13.4');\n} catch (err) {\n  await claw.reportActionFailure(action.action_id, err.message);\n}\n```\n\nPython uses the same shape with `snake_case`. Full reference: [`sdk/README.md`](./sdk/README.md). Step-by-step walkthrough: [`QUICK-START.md`](./QUICK-START.md).\n\n---\n\n## Deploy\n\n### Local\n\n```bash\nnpx dashclaw up\n```\n\nInstalls the app, provisions Postgres (Docker or embedded), generates secrets, mints your API key, applies migrations, starts on :3000, and offers to wire Claude Code hooks — one command, no accounts required.\n\nComing from the hosted trial? Click **Export workspace** on your trial's `/connect` card, then run `dashclaw import \u003cbundle.json\u003e` against your new instance — policies, decisions, action history, agents, and assumptions carry over. API keys and secret values never ride a bundle; mint fresh ones here.\n\n### Cloud\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fucsandman%2FDashClaw\u0026env=DATABASE_URL,DASHCLAW_API_KEY,ENCRYPTION_KEY,NEXTAUTH_SECRET,NEXTAUTH_URL,CRON_SECRET,DASHCLAW_LOCAL_ADMIN_PASSWORD\u0026envDescription=Required%20DashClaw%20configuration.%20See%20.env.example%20for%20details.\u0026envLink=https%3A%2F%2Fgithub.com%2Fucsandman%2FDashClaw%2Fblob%2Fmain%2F.env.example\u0026project-name=my-dashclaw\u0026repository-name=my-dashclaw\u0026products=%5B%7B%22type%22%3A%22integration%22%2C%22integrationSlug%22%3A%22neon%22%2C%22productSlug%22%3A%22neon%22%2C%22protocol%22%3A%22storage%22%7D%5D\u0026skippable-integrations=1)\n\n**$0 to deploy.** Vercel free tier plus Neon free tier. Click the button, add the Neon integration when prompted, fill in the env vars listed in [`.env.example`](./.env.example). The schema migration runs as part of the build, so there is no manual migration step.\n\n### After deploy\n\n1. **Open the app** at `https://your-app.vercel.app` and sign in.\n2. **Copy the integration snippet** from Mission Control. It pre-fills your base URL and gives you a one-click API key.\n3. **Run it.** `node --env-file=.env demo.js` from any client environment and watch the governed action land in your decisions ledger.\n\n### Optional\n\n- **Live decision stream.** Add [Upstash Redis](https://upstash.com) credentials (`UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN`) to get cross-instance event replay. Without it, Mission Control uses in-memory events, which is fine for getting started but does not persist across serverless invocations.\n- **Hosted trial mode.** If you want DashClaw itself to mint trial workspaces (operator deployments only), follow [`docs/hosted-deployment-runbook.md`](./docs/hosted-deployment-runbook.md). That path needs Turnstile, cleanup secrets, and an operator-managed cron.\n- **Self-host without Vercel.** A Dockerfile and standalone `next start` path are available; see [`Dockerfile`](./Dockerfile). The schema migration in `scripts/auto-migrate.mjs` is idempotent and safe to re-run.\n\n---\n\n## Durable execution finality\n\nApproved actions now carry a terminal outcome separate from their lifecycle status. Five states, one-shot transitions, repository-level enforcement:\n\n| State | Meaning |\n|---|---|\n| `pending` | Approved, no outcome reported yet. |\n| `completed` | Finished successfully. Set by the agent. |\n| `partial` | Started but did not finish. Set by the agent with a progress payload. |\n| `failed` | Attempted and errored. Set by the agent with an error message. |\n| `lost_confirmation` | Timeout exceeded without a report. Set by the cron sweep. |\n\n```javascript\n// Retry-safe poll before re-trying any approved action\nconst outcome = await claw.getActionOutcome(actionId);\nswitch (outcome.status) {\n  case 'pending':           /* still in flight, wait */ break;\n  case 'completed':         /* already executed, skip */ break;\n  case 'failed':            /* safe to retry */ break;\n  case 'lost_confirmation': /* sweep gave up, safe to retry */ break;\n  case 'partial':           /* clean up then retry */ break;\n}\n\n// Make the create itself retry-safe\nconst key = claw.deriveIdempotencyKey({\n  agent_id: 'deploy-bot', action_type: 'deploy', scope: 'prod-us-east', request_id,\n});\nawait claw.createAction({ /* ... */, idempotency_key: key });\n```\n\n`POST /api/actions/[actionId]/outcome` is one-shot: the first call wins, every subsequent POST returns 409 with `current_status`. A daily Vercel cron (hourly externally on Pro or via GitHub Actions) marks stale pending rows as `lost_confirmation` and emits a `signal.detected` event so subscribed webhooks know to investigate. Full spec: [`docs/architecture/durable-execution-finality.md`](./docs/architecture/durable-execution-finality.md).\n\n---\n\n## Safety and governance model\n\nDashClaw is not observability. It is control before execution. The model:\n\n1. **Every agent action is evaluated against active policies before the action runs.** Policies are declarative; the policy builder ships with ten pre-built safety switches (Deploy Gate, Risk Threshold, Rate Limiter, Evidence Required, and others), an AI generator, and YAML import.\n2. **Sensitive actions require human approval.** Approvals route to the dashboard, the CLI (`@dashclaw/cli`), the mobile PWA at `/approve`, Telegram, or Discord. Same action, any surface.\n   Approval *volume* is governed too: when one policy (or the fleet) exceeds its interruption budget (default 10 per policy / 30 fleet-wide per 15-minute window), per-action pings collapse into a single flood banner on `/approvals` with pause-rule and bulk-resolve controls — pending approvals are never auto-resolved, and the platform's own verification traffic is excluded from flood detection.\n3. **Every decision is recorded.** The decisions ledger is replayable: declared goal, reasoning, matched policies, assumptions, signals, and the final outcome.\n4. **Outcomes are durable.** The five-state finality machine guarantees no silent double-execute on retry, and the sweep catches lost confirmations.\n5. **Evidence is exportable.** Compliance evidence bundles (signed manifests, JSON exports) are produced from real action records, not synthetic fixtures.\n6. **Prompt injection scanning is on by default.** Declared goals are scanned for injection patterns. High-confidence system-override patterns (\"ignore previous instructions\" and family) force a `block` decision at guard time — halted mechanically on enforcing surfaces, honored by cooperative callers ([enforcement boundary](./docs/architecture/enforcement-boundary.md)); lower-severity patterns (delimiter injection, exfiltration probes) raise a `warn`.\n7. **Intent can be graded from evidence, not just declaration.** SDK, MCP, and REST callers can attach the actual act — the shell command, HTTP request, SQL statement, or file write — and the server classifies it deterministically, folding derived risk in so evidence can only raise a score, never lower it. Decisions record `intent_source: evidence | declared`, a `require_evidence` policy escalates declared-only calls, and posture shows the mix. This defeats a lying *model* (the wrapper authors the payload, not the LLM); a lying *process* is only stopped by credential custody via the capability registry ([enforcement boundary](./docs/architecture/enforcement-boundary.md)).\n8. **Agent identity is cryptographically verified.** Agents may present a JWKS-verified JWT instead of self-asserting `agent_id`. DashClaw checks the signature against the issuer's published keys (EdDSA / RSA / ECDSA), rejects replayed tokens, and can bind a token to its intended action — the verified `sub` overrides any body-supplied `agent_id`. Fail-soft on the issuer side: a downed issuer never blocks a decision (the token degrades to unverified). Replay protection defaults to `required`, so a verified token *does* fail closed when the replay store is unreachable; API-key callers are unaffected. See [`docs/agent-identity.md`](./docs/agent-identity.md).\n\nThe full architecture map lives in [`PROJECT_DETAILS.md`](./PROJECT_DETAILS.md). The runtime API contract is in [`docs/architecture/runtime-api.md`](./docs/architecture/runtime-api.md).\n\n---\n\n## Approvals beyond the dashboard\n\n| Surface | Purpose | Setup |\n|---|---|---|\n| Dashboard (`/approvals`) | Primary inbox for operators in front of a browser. | None. |\n| CLI (`@dashclaw/cli`) | Terminal-first inbox. `dashclaw approvals`, `dashclaw approve \u003cid\u003e`. | `npm install -g @dashclaw/cli` |\n| Mobile PWA (`/approve`) | Phone-first allow/deny with risk score and policy. Add to home screen. | None. |\n| Telegram | Inline Approve/Reject buttons in an admin chat. | Optional. See [`docs/telegram-setup.md`](./docs/telegram-setup.md). |\n| Discord | Inline Approve/Deny on DM embeds. | Optional. See `.env.example` (Discord section). |\n\n`waitForApproval()` unblocks near-instantly over SSE when the approval resolves, falling back to ~5-second polling where SSE is unavailable — regardless of which surface resolves the action. All surfaces hit the same `/api/approvals/[actionId]` endpoint.\n\n---\n\n## Beyond the basics\n\n| Feature | Description | Docs |\n|---|---|---|\n| Drift detection | Statistical reasoning and metric drift across sessions. | [SDK: Learning Loop](./sdk/README.md#learning-loop) |\n| Capability registry | Wrap real HTTP APIs with per-agent access rules and health monitoring. | [Capability Runtime](./sdk/README.md#capability-runtime) |\n| Workflow engine | Compose governance into multi-step runs with variables, `continue_on_failure`, and resume from checkpoint. | [DEMO.md](./DEMO.md) |\n| Scoring profiles | Multi-dimensional evaluation with weighted composites and auto-calibration. | [SDK: Scoring](./sdk/README.md#scoring-profiles) |\n| Recovery recipes | Six built-in recipes mapping signals to remediations. | [SDK: Learning](./sdk/README.md#learning-loop) |\n| Agent profiles | Per-agent governance dashboard at `/agents/[agentId]`. | [PROJECT_DETAILS.md](./PROJECT_DETAILS.md) |\n| Analytics | Cost trends, action volume, agent and type breakdowns, policy enforcement stats, and token efficiency at `/analytics`. | [PROJECT_DETAILS.md](./PROJECT_DETAILS.md) |\n| Doctor | `npm run doctor` (local) or `dashclaw doctor` (remote + machine checks). Report-only by default (the write-path canary proves inserts land using synthetic, self-cleaning rows in an isolated canary org); `--fix` applies safe auto-fixes (migrations, default policy, CORS, timestamp hygiene, stale mcp-server lib, and more). | [SDK README](./sdk/README.md) |\n| Live host canary | `scripts/live-canary.mjs` probes your production hosts hourly as a real unauthenticated client (marketing, docs, demo entry, trial-mint fail-closed, OAuth discovery, MCP handshake) from a GitHub Actions cron and files its verdict to `POST /api/live-canary`. Failures render on `/setup#live-canary` and raise a posture auditability finding. | [.github/workflows/live-canary.yml](./.github/workflows/live-canary.yml) |\n| Coverage truth | Every action row records how it closed (`close_source`: real outcome vs Stop-hook auto-close vs created-terminal). The Claude Code Stop hook separately reports per-turn expected-vs-recorded tool-use counts to `POST /api/coverage`, rendered as a Coverage column on `/agents` — with an explicit \"no evidence\" state so silence never reads as health. A posture finding fires when a real agent's coverage drops below 90%, deep-linking to `/agents`. | [PROJECT_DETAILS.md](./PROJECT_DETAILS.md) |\n| Fleet attribution | Every action carries its harness session (`harness_session_id`); subagent leaves carry their instance uuid (`subagent_uuid`); spawn rows carry the spawned agent's uuid (`outcome_metadata.spawned_agent_uuid`) — so a multi-agent fan-out reads as one governed unit with per-leaf attribution, joined from evidence, never guessed. A Fan-outs panel on `/agents` lists recent sessions and deep-links to the matching `/swarm` graph. | [PROJECT_DETAILS.md](./PROJECT_DETAILS.md) |\n\n---\n\n## Documentation\n\n**[docs/README.md](./docs/README.md) is the full documentation index** — ordered by adoption journey (understand → try → connect → operate → reference). Highlights:\n\n- [Concepts](./docs/concepts.md): the whole mental model on one page — primitives, the loop, risk scoring, what \"block\" means per surface.\n- [Quick start](./QUICK-START.md): from zero to first governed action.\n- [Governing Claude Code](./docs/integrations/claude-code.md) · [Governing agents over MCP](./docs/integrations/mcp.md): the two highest-traffic integration guides.\n- [Operating DashClaw](./docs/operations.md): policies, approvals, posture, the emergency halt, doctor.\n- [Troubleshooting](./docs/troubleshooting.md): the errors you'll actually see, with fixes.\n- **[/explain](https://dashclaw.io/explain/)** — interactive explainer: the governance loop, a guard-decision simulator, and a policy playground.\n- [Node SDK reference](./sdk/README.md): canonical reference for the `dashclaw` npm package.\n- [Python SDK reference](./sdk-python/README.md): same surface, snake_case.\n- [SDK parity matrix](./docs/sdk-parity.md): Node v2 vs Python coverage.\n- [Agent identity guide](./docs/agent-identity.md): JWKS verification, replay protection, and action binding (Phase 2 / 2b / 2c).\n- [Runtime API contract](./docs/architecture/runtime-api.md): minimal core governance endpoints.\n- [Guard enforcement contract](./docs/guard-enforcement-contract.md): fail-closed degradation, evaluation deadline, MCP/hook unavailable policy, idempotency keys, org kill switch.\n- [API inventory](./docs/api-inventory.md): full route list with maturity tier.\n- [Durable execution finality spec](./docs/architecture/durable-execution-finality.md): five-state machine, sweep, idempotency.\n- [Architecture map](./PROJECT_DETAILS.md): system boundaries and SDK surface inventory.\n- [Changelog](./CHANGELOG.md): release history.\n- [Security guide](./docs/SECURITY.md): operator-facing security model, controls, and coordinated disclosure.\n\n---\n\n## Project status\n\nHonest expectations, stated plainly:\n\n- **Young and fast-moving.** First commit February 2026; releases land near-daily. The API surface is explicitly tiered for exactly this reason — 57 stable routes pinned in the [OpenAPI contract](./docs/openapi/critical-stable.openapi.json), 24 beta, 251 experimental. Build against stable; experimental routes can change without notice.\n- **Proven by dogfood, not by scale.** The core loop is exercised continuously by the maintainer's own agent fleet (the screenshots above) and by a CI policy-smoke harness that live-proves the public claims on every push. External production deployments are early. Treat this as young infrastructure that takes correctness seriously, not a battle-tested incumbent.\n- **AI-maintained, human-governed.** Day-to-day maintenance is done by an AI agent under the human-held charter in [MAINTAINER.md](./MAINTAINER.md); risk-bearing invariants (blocks are absolute, no self-approval, humans ratify policy changes, credentials stay human) cannot be changed by the maintainer. The [maintainer log](./docs/maintainer-log.md) records every decision in public.\n\n## License\n\n[MIT](./LICENSE)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cbr /\u003e\n  \u003cimg src=\"public/images/github-social-preview-ps.png\" alt=\"Practical Systems\" width=\"600\" /\u003e\n  \u003cbr /\u003e\n  \u003csub\u003eBuilt by \u003ca href=\"https://practicalsystems.io\"\u003ePractical Systems\u003c/a\u003e\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucsandman%2Fdashclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fucsandman%2Fdashclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucsandman%2Fdashclaw/lists"}