{"id":45897575,"url":"https://github.com/memodb-io/cueclaw","last_synced_at":"2026-03-03T00:01:41.213Z","repository":{"id":340940697,"uuid":"1165484167","full_name":"memodb-io/cueclaw","owner":"memodb-io","description":"Orchestrate agent workflows with natural language. Claude Agent SDK → execution plans → confirm → run in the background.","archived":false,"fork":false,"pushed_at":"2026-02-28T09:24:41.000Z","size":562,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T23:06:07.792Z","etag":null,"topics":["ai-agents","ai-assistant","claude","claude-agent-sdk","claude-code","claude-skills","clawdbot","typescript","workflow-engine"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/memodb-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"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-02-24T08:05:16.000Z","updated_at":"2026-02-28T09:23:44.000Z","dependencies_parsed_at":"2026-02-28T22:03:07.441Z","dependency_job_id":null,"html_url":"https://github.com/memodb-io/cueclaw","commit_stats":null,"previous_names":["memodb-io/cueclaw"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/memodb-io/cueclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memodb-io%2Fcueclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memodb-io%2Fcueclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memodb-io%2Fcueclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memodb-io%2Fcueclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/memodb-io","download_url":"https://codeload.github.com/memodb-io/cueclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/memodb-io%2Fcueclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29987654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T22:42:38.399Z","status":"ssl_error","status_checked_at":"2026-03-01T22:41:51.863Z","response_time":124,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agents","ai-assistant","claude","claude-agent-sdk","claude-code","claude-skills","clawdbot","typescript","workflow-engine"],"created_at":"2026-02-27T21:26:59.516Z","updated_at":"2026-03-03T00:01:40.855Z","avatar_url":"https://github.com/memodb-io.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"CueClaw\" width=\"400\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  An AI workflow orchestrator that turns natural language into executable DAGs. Built on the \u003ca href=\"https://docs.anthropic.com/en/docs/claude-agent-sdk\"\u003eClaude Agent SDK\u003c/a\u003e.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/cueclaw\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/cueclaw\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/memodb-io/cueclaw/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/memodb-io/cueclaw/ci.yml?branch=main\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/memodb-io/cueclaw/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/memodb-io/cueclaw\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/node/v/cueclaw\" alt=\"Node.js\" /\u003e\n\u003c/p\u003e\n\n## How It Works\n\n1. **Describe** what you want in plain language\n2. **Review** the generated execution plan (DAG)\n3. **Confirm**, and CueClaw runs it in the background as a daemon\n\n```\nYou: \"Every day at 10am, scrape GitHub Trending for the top 10 projects,\n      summarize each with stars/language/description, and send the digest\n      to me on Telegram.\"\n\nCueClaw:\n  ┌─ Plan: GitHub Trending Digest ─────────────┐\n  │ Trigger: cron (0 10 * * *)                 │\n  │                                            │\n  │ 1. Fetch GitHub Trending page              │\n  │ 2. Extract top 10 projects with metadata   │\n  │    └─ depends on: step 1                   │\n  │ 3. Generate formatted digest summary       │\n  │    └─ depends on: step 2                   │\n  │ 4. Send digest via Telegram                │\n  │    └─ depends on: step 3                   │\n  │                                            │\n  │ [Y] Confirm  [M] Modify  [N] Cancel        │\n  └────────────────────────────────────────────┘\n```\n\n### More Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eX (Twitter) Auto Engage\u003c/b\u003e — poll trigger, daily cron summary\u003c/summary\u003e\n\n```\nYou: \"Every 30 minutes, check my X timeline for trending AI/LLM tweets,\n      reply with a professional but friendly tone, and post a daily\n      original tweet summarizing the day's trends.\"\n\nCueClaw:\n  ┌─ Plan: X (Twitter) Auto Engage ────────────┐\n  │ Trigger: poll (30min)                      │\n  │                                            │\n  │ 1. Fetch timeline \u0026 trending topics        │\n  │ 2. Filter AI/LLM related tweets            │\n  │    └─ depends on: step 1                   │\n  │ 3. Generate \u0026 post replies                 │\n  │    └─ depends on: step 2                   │\n  │ 4. Daily: compose \u0026 post trend summary     │\n  │    └─ cron: 0 21 * * *                     │\n  └────────────────────────────────────────────┘\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGitHub Issue to Draft PR\u003c/b\u003e — poll trigger, multi-step DAG\u003c/summary\u003e\n\n```\nYou: \"Monitor my repo for issues assigned to me. Create a branch,\n      analyze the issue, generate an implementation plan, and open\n      a Draft PR linking the issue.\"\n\nCueClaw:\n  ┌─ Plan: Issue Auto PR ──────────────────────┐\n  │ Trigger: poll (60s)                        │\n  │                                            │\n  │ 1. Clone repo \u0026 create feature branch      │\n  │ 2. Analyze issue \u0026 generate plan           │\n  │    └─ depends on: step 1                   │\n  │ 3. Commit plan \u0026 create Draft PR           │\n  │    └─ depends on: step 2                   │\n  │ 4. Notify via Telegram                     │\n  │    └─ depends on: step 3                   │\n  └────────────────────────────────────────────┘\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePR Review Loop\u003c/b\u003e — interactive commands via poll trigger\u003c/summary\u003e\n\n```\nYou: \"Watch my PRs. If someone comments /execute, run the plan in PLAN.md.\n      If they comment /modify, update the plan. If /merge, squash-merge\n      and close the linked issue.\"\n\nCueClaw:\n  ┌─ Plan: PR Review Loop ─────────────────────┐\n  │ Trigger: poll (60s)                        │\n  │                                            │\n  │ 1. Parse trigger data for PR \u0026 command     │\n  │ 2. Execute command (run/modify/merge)      │\n  │    └─ depends on: step 1                   │\n  │ 3. Comment result on PR \u0026 notify user      │\n  │    └─ depends on: step 2                   │\n  └────────────────────────────────────────────┘\n```\n\n\u003c/details\u003e\n\n## Features\n\n**Core**\n- **Natural language in, workflow out** — Describe \"when X happens, do Y\". No YAML/JSON authoring.\n- **Human-in-the-loop** — Review the generated DAG before anything runs. Modify or cancel at any point.\n- **Multi-turn planner** — The planner asks clarifying questions, stores credentials, then generates the workflow.\n- **Parallel DAG execution** — Independent steps run concurrently via `Promise.all`. Dependencies are respected.\n\n**Channels**\n- **TUI** — Interactive terminal UI with themes, keyboard shortcuts, and real-time execution views.\n- **WhatsApp** — Baileys-based. QR code auth, inline confirmation, typing indicators.\n- **Telegram** — Grammy-based. Inline keyboard buttons, message chunking, callback queries.\n\n**Infrastructure**\n- **Daemon** — Runs as a launchd (macOS) or systemd (Linux) service with auto-restart on crash.\n- **Triggers** — Poll scripts, cron schedules, or manual execution.\n- **Concurrency control** — GroupQueue with global cap and per-workflow serialization.\n- **Container isolation** (optional) — Docker execution with filesystem isolation, mount allowlists, and stdin-only secret delivery. Defaults to local mode with safety hooks.\n- **Structured logging** — pino to `~/.cueclaw/logs/`, per-workflow execution logs, TUI log stream.\n\n## Quick Start\n\nRuntime: **Node.js 22+**.\n\n```bash\nnpm install -g cueclaw@latest\ncueclaw config set claude.api_key $ANTHROPIC_API_KEY\ncueclaw\n```\n\nFrom source:\n\n```bash\ngit clone https://github.com/memodb-io/cueclaw.git\ncd cueclaw \u0026\u0026 pnpm install \u0026\u0026 pnpm build\npnpm dev  # or: node dist/cli.js\n```\n\nOptional: [Docker](https://docker.com/products/docker-desktop) for container isolation, WhatsApp / Telegram for bot channels.\n\n## Architecture\n\n```mermaid\nflowchart TB\n    subgraph Channels\n        TUI[TUI\u003cbr/\u003e\u003csmall\u003eInk / React\u003c/small\u003e]\n        WA[WhatsApp\u003cbr/\u003e\u003csmall\u003eBaileys\u003c/small\u003e]\n        TG[Telegram\u003cbr/\u003e\u003csmall\u003eGrammy\u003c/small\u003e]\n    end\n\n    subgraph Core\n        Router[Message Router]\n        PS[Planner Session\u003cbr/\u003e\u003csmall\u003emulti-turn LLM\u003c/small\u003e]\n        Exec[Executor\u003cbr/\u003e\u003csmall\u003eparallel DAG\u003c/small\u003e]\n        AR[Agent Runner\u003cbr/\u003e\u003csmall\u003eClaude Agent SDK\u003c/small\u003e]\n    end\n\n    subgraph Daemon\n        TL[Trigger Loop\u003cbr/\u003e\u003csmall\u003epoll / cron\u003c/small\u003e]\n        GQ[GroupQueue\u003cbr/\u003e\u003csmall\u003econcurrency control\u003c/small\u003e]\n    end\n\n    TUI \u0026 WA \u0026 TG --\u003e Router\n    Router --\u003e PS\n    PS --\u003e|Workflow DAG| Router\n    Router --\u003e|User confirms| Exec\n    Exec --\u003e AR\n    AR --\u003e|local| SDK[Claude Agent SDK\u003cbr/\u003e\u003csmall\u003equery\u0026#40;\u0026#41;\u003c/small\u003e]\n    AR --\u003e|container| Docker[Docker Container]\n    Exec --\u003e DB[(SQLite)]\n    TL --\u003e GQ --\u003e Exec\n    Exec --\u003e|notify| Router\n    Router --\u003e TUI \u0026 WA \u0026 TG\n```\n\nSingle Node.js process. Each workflow step runs in its own agent session. Data flows between steps via `$steps.{id}.output` references. The daemon manages trigger evaluation and workflow execution with crash recovery.\n\nSee [docs/architecture.md](docs/architecture.md) for the full design.\n\n## Commands\n\n**CLI**\n\n```bash\ncueclaw                        # Launch TUI (default)\ncueclaw new \"description\"      # Create workflow directly\ncueclaw list                   # List all workflows\ncueclaw status \u003cid\u003e            # Workflow details\ncueclaw pause|resume|delete    # Lifecycle management\ncueclaw daemon start|stop|status|install|uninstall|logs\ncueclaw config get|set         # Configuration management\ncueclaw setup                  # First-run validation\n```\n\n**TUI Slash Commands**\n\n```\n/new [description]     Create a new workflow\n/list                  List all workflows\n/status \u003cid\u003e           Workflow status\n/cancel \u003cid\u003e           Cancel running workflow\n/bot start|status      Manage bot channels\n/daemon start|stop     Daemon control\n/theme [name]          Switch theme (default, mono, ocean)\n/help                  Show all commands\n```\n\n## Project Structure\n\n```\nsrc/\n├── cli.ts                 # CLI entry point (commander)\n├── config.ts              # YAML config + Zod validation\n├── db.ts                  # SQLite persistence (WAL mode)\n├── planner.ts             # LLM → Workflow DAG generation\n├── planner-session.ts     # Multi-turn planner conversation\n├── executor.ts            # Parallel DAG execution engine\n├── agent-runner.ts        # Claude Agent SDK wrapper (local + container)\n├── router.ts              # Message routing across channels\n├── daemon.ts              # Background process + PID management\n├── service.ts             # launchd / systemd integration\n├── trigger-loop.ts        # Poll + cron trigger evaluation\n├── container-runner.ts    # Docker container execution\n├── container-runtime.ts   # Image management (build / pull)\n├── channels/\n│   ├── tui.ts             # TUI channel\n│   ├── whatsapp.ts        # WhatsApp (Baileys)\n│   └── telegram.ts        # Telegram (Grammy)\n└── tui/\n    ├── app.tsx            # Main TUI application\n    ├── commands/          # Slash command registry\n    ├── hooks/             # Custom React hooks\n    ├── messages/          # Per-type message components\n    └── theme/             # Theme system (3 built-in themes)\n```\n\n## Documentation\n\n| Doc | Description |\n| --- | --- |\n| [PLAN.md](PLAN.md) | Implementation plan and milestones |\n| [plans/](plans/) | Phase-by-phase implementation details |\n| [docs/architecture.md](docs/architecture.md) | System design and security model |\n| [docs/types.md](docs/types.md) | Workflow Protocol, Channel interface, DB schema |\n| [docs/config.md](docs/config.md) | Configuration and CLI reference |\n| [docs/testing.md](docs/testing.md) | Test strategy |\n\n## Contributing\n\nContributions are welcome. CueClaw follows a **skills-over-features** philosophy — the core stays minimal, and domain-specific capabilities live as skills in `.claude/skills/`.\n\n```bash\npnpm install          # Install dependencies\npnpm test             # Run tests (~309 tests, 33 files)\npnpm lint             # Lint\npnpm typecheck        # Type check\n```\n\nSee [docs/testing.md](docs/testing.md) for test conventions (co-located tests, in-memory SQLite, mock patterns).\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmemodb-io%2Fcueclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmemodb-io%2Fcueclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmemodb-io%2Fcueclaw/lists"}