https://github.com/memodb-io/cueclaw

Orchestrate agent workflows with natural language. Claude Agent SDK → execution plans → confirm → run in the background.
https://github.com/memodb-io/cueclaw

ai-agents ai-assistant claude claude-agent-sdk claude-code claude-skills clawdbot typescript workflow-engine

Last synced: 4 months ago
JSON representation

Orchestrate agent workflows with natural language. Claude Agent SDK → execution plans → confirm → run in the background.

Host: GitHub
URL: https://github.com/memodb-io/cueclaw
Owner: memodb-io
License: apache-2.0
Created: 2026-02-24T08:05:16.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-02-28T09:24:41.000Z (4 months ago)
Last Synced: 2026-02-28T23:06:07.792Z (4 months ago)
Topics: ai-agents, ai-assistant, claude, claude-agent-sdk, claude-code, claude-skills, clawdbot, typescript, workflow-engine
Language: TypeScript
Size: 549 KB
Stars: 2
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

An AI workflow orchestrator that turns natural language into executable DAGs. Built on the Claude Agent SDK.

Node.js

## How It Works

1. **Describe** what you want in plain language
2. **Review** the generated execution plan (DAG)
3. **Confirm**, and CueClaw runs it in the background as a daemon

```
You: "Every day at 10am, scrape GitHub Trending for the top 10 projects,
summarize each with stars/language/description, and send the digest
to me on Telegram."

CueClaw:
┌─ Plan: GitHub Trending Digest ─────────────┐
│ Trigger: cron (0 10 * * *) │
│ │
│ 1. Fetch GitHub Trending page │
│ 2. Extract top 10 projects with metadata │
│ └─ depends on: step 1 │
│ 3. Generate formatted digest summary │
│ └─ depends on: step 2 │
│ 4. Send digest via Telegram │
│ └─ depends on: step 3 │
│ │
│ [Y] Confirm [M] Modify [N] Cancel │
└────────────────────────────────────────────┘
```

### More Examples

X (Twitter) Auto Engage — poll trigger, daily cron summary

```
You: "Every 30 minutes, check my X timeline for trending AI/LLM tweets,
reply with a professional but friendly tone, and post a daily
original tweet summarizing the day's trends."

CueClaw:
┌─ Plan: X (Twitter) Auto Engage ────────────┐
│ Trigger: poll (30min) │
│ │
│ 1. Fetch timeline & trending topics │
│ 2. Filter AI/LLM related tweets │
│ └─ depends on: step 1 │
│ 3. Generate & post replies │
│ └─ depends on: step 2 │
│ 4. Daily: compose & post trend summary │
│ └─ cron: 0 21 * * * │
└────────────────────────────────────────────┘
```

GitHub Issue to Draft PR — poll trigger, multi-step DAG

```
You: "Monitor my repo for issues assigned to me. Create a branch,
analyze the issue, generate an implementation plan, and open
a Draft PR linking the issue."

CueClaw:
┌─ Plan: Issue Auto PR ──────────────────────┐
│ Trigger: poll (60s) │
│ │
│ 1. Clone repo & create feature branch │
│ 2. Analyze issue & generate plan │
│ └─ depends on: step 1 │
│ 3. Commit plan & create Draft PR │
│ └─ depends on: step 2 │
│ 4. Notify via Telegram │
│ └─ depends on: step 3 │
└────────────────────────────────────────────┘
```

PR Review Loop — interactive commands via poll trigger

```
You: "Watch my PRs. If someone comments /execute, run the plan in PLAN.md.
If they comment /modify, update the plan. If /merge, squash-merge
and close the linked issue."

CueClaw:
┌─ Plan: PR Review Loop ─────────────────────┐
│ Trigger: poll (60s) │
│ │
│ 1. Parse trigger data for PR & command │
│ 2. Execute command (run/modify/merge) │
│ └─ depends on: step 1 │
│ 3. Comment result on PR & notify user │
│ └─ depends on: step 2 │
└────────────────────────────────────────────┘
```

## Features

**Core**
- **Natural language in, workflow out** — Describe "when X happens, do Y". No YAML/JSON authoring.
- **Human-in-the-loop** — Review the generated DAG before anything runs. Modify or cancel at any point.
- **Multi-turn planner** — The planner asks clarifying questions, stores credentials, then generates the workflow.
- **Parallel DAG execution** — Independent steps run concurrently via `Promise.all`. Dependencies are respected.

**Channels**
- **TUI** — Interactive terminal UI with themes, keyboard shortcuts, and real-time execution views.
- **WhatsApp** — Baileys-based. QR code auth, inline confirmation, typing indicators.
- **Telegram** — Grammy-based. Inline keyboard buttons, message chunking, callback queries.

**Infrastructure**
- **Daemon** — Runs as a launchd (macOS) or systemd (Linux) service with auto-restart on crash.
- **Triggers** — Poll scripts, cron schedules, or manual execution.
- **Concurrency control** — GroupQueue with global cap and per-workflow serialization.
- **Container isolation** (optional) — Docker execution with filesystem isolation, mount allowlists, and stdin-only secret delivery. Defaults to local mode with safety hooks.
- **Structured logging** — pino to `~/.cueclaw/logs/`, per-workflow execution logs, TUI log stream.

## Quick Start

Runtime: **Node.js 22+**.

```bash
npm install -g cueclaw@latest
cueclaw config set claude.api_key $ANTHROPIC_API_KEY
cueclaw
```

From source:

```bash
git clone https://github.com/memodb-io/cueclaw.git
cd cueclaw && pnpm install && pnpm build
pnpm dev # or: node dist/cli.js
```

Optional: [Docker](https://docker.com/products/docker-desktop) for container isolation, WhatsApp / Telegram for bot channels.

## Architecture

```mermaid
flowchart TB
subgraph Channels
TUI[TUI
Ink / React]
WA[WhatsApp
Baileys]
TG[Telegram
Grammy]
end

subgraph Core
Router[Message Router]
PS[Planner Session
multi-turn LLM]
Exec[Executor
parallel DAG]
AR[Agent Runner
Claude Agent SDK]
end

subgraph Daemon
TL[Trigger Loop
poll / cron]
GQ[GroupQueue
concurrency control]
end

Single 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.

See [docs/architecture.md](docs/architecture.md) for the full design.

## Commands

**CLI**

**TUI Slash Commands**

```
/new [description] Create a new workflow
/list List all workflows
/status Workflow status
/cancel Cancel running workflow
/bot start|status Manage bot channels
/daemon start|stop Daemon control
/theme [name] Switch theme (default, mono, ocean)
/help Show all commands
```

## Project Structure

```
src/
├── cli.ts # CLI entry point (commander)
├── config.ts # YAML config + Zod validation
├── db.ts # SQLite persistence (WAL mode)
├── planner.ts # LLM → Workflow DAG generation
├── planner-session.ts # Multi-turn planner conversation
├── executor.ts # Parallel DAG execution engine
├── agent-runner.ts # Claude Agent SDK wrapper (local + container)
├── router.ts # Message routing across channels
├── daemon.ts # Background process + PID management
├── service.ts # launchd / systemd integration
├── trigger-loop.ts # Poll + cron trigger evaluation
├── container-runner.ts # Docker container execution
├── container-runtime.ts # Image management (build / pull)
├── channels/
│ ├── tui.ts # TUI channel
│ ├── whatsapp.ts # WhatsApp (Baileys)
│ └── telegram.ts # Telegram (Grammy)
└── tui/
├── app.tsx # Main TUI application
├── commands/ # Slash command registry
├── hooks/ # Custom React hooks
├── messages/ # Per-type message components
└── theme/ # Theme system (3 built-in themes)
```

## Documentation

| Doc | Description |
| --- | --- |
| [PLAN.md](PLAN.md) | Implementation plan and milestones |
| [plans/](plans/) | Phase-by-phase implementation details |
| [docs/architecture.md](docs/architecture.md) | System design and security model |
| [docs/types.md](docs/types.md) | Workflow Protocol, Channel interface, DB schema |
| [docs/config.md](docs/config.md) | Configuration and CLI reference |
| [docs/testing.md](docs/testing.md) | Test strategy |

## Contributing

Contributions are welcome. CueClaw follows a **skills-over-features** philosophy — the core stays minimal, and domain-specific capabilities live as skills in `.claude/skills/`.

```bash
pnpm install # Install dependencies
pnpm test # Run tests (~309 tests, 33 files)
pnpm lint # Lint
pnpm typecheck # Type check
```

See [docs/testing.md](docs/testing.md) for test conventions (co-located tests, in-memory SQLite, mock patterns).

## License

Apache-2.0

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/memodb-io/cueclaw

Awesome Lists containing this project

README