agentcue

AgentCue

Local-first mission control for your AI agent workforce.

Run a fleet of AI CLI agents (Claude Code, Codex, …) like employees — chat with them, orchestrate them on a visual canvas, approve their actions from your phone, and audit everything they did. A small FastAPI server + a single-file cockpit. No Docker, no database server, no build step. The control plane and all state stay on your machine (prompts go to your AI provider, as with any AI CLI).

Extracted from a system that has been running a real one-person operation daily since early 2026 — research pipelines, content generation, daily ops, all supervised through this cockpit.

Flow canvas	Employees

Why AgentCue

	AgentCue	n8n / Windmill / Dify	GitHub Agent HQ
AI CLI sessions as “employees” (persistent memory, resume)	✅ core concept	❌	partial, GitHub-centric
Runs on a laptop, zero infra	✅ python server.py	typically Docker	cloud
Human-in-the-loop approvals (web + Telegram, first-response-wins, timeout = deny)	✅ built-in	varies	✅
State stays local (JSONL + SQLite, greppable)	✅	self-host possible	❌
Visual flow canvas with per-node results	✅	✅ (richer)	❌

If you want a general-purpose integration platform with 500 connectors, use n8n. If you run AI coding agents all day and want a cockpit — a place where your agents are employees with names, memory, task queues, and an approval inbox — that’s AgentCue.

Features

• 💬 Employees — each Claude Code session is a contact: named, persistent memory (claude -p --resume), streaming replies, per-message “allow tools” switch. Session rescue relaunches any CLI window after a reboot.
• 🎨 Canvas — drag-and-drop flow editor (Drawflow): action / claude / codex / gate / shell / fetch / tg / wait / readfile / writefile / kb / swarm / tournament nodes. Runs always execute the canvas you see (no stale-version footgun); every run stores a snapshot of the flow definition + per-node inputs/outputs/duration. Click a node to inspect its result.
• 🔒 Approval inbox — gates pause a flow and land in the inbox (web) and on Telegram (buttons). First response wins across channels; every decision is audited (when, via, comment); timeouts deny by default, never approve.
• 🔁 Retry semantics (n8n-style) — re-run the original flow definition, or the current saved version (picks up fixes), with lineage tracking.
• 📅 Daily todos — recurring manual/auto task definitions, checked off in the UI; morning Telegram push and .ics calendar export via included scripts (ops/) you schedule yourself.
• 🩺 Self-healing — on-demand scheduled-task health scan (Windows); one click dispatches an AI agent to diagnose the failure and report an incident card.
• 🔎 Local knowledge base — BM25 search (CJK-friendly) over any markdown folders you point it at.
• Security posture — loopback-only enforced at startup, CSRF/DNS-rebind guards, path containment on writes, SSRF guard on fetch, no template interpolation into shell. Threat model and known limits: SECURITY.md.

Quickstart

git clone https://github.com/hsienchuc/agentcue && cd agentcue
pip install -r requirements.txt
python server.py          # → http://127.0.0.1:8899

Requirements: Python 3.11+, and at least one AI CLI on PATH — Claude Code (primary), Codex CLI (optional red-team engine).

Optional:

• mkdir -p data(Windows: md data)— runtime dir, auto-created on first server start.
• cp examples/agentcue.example.json agentcue.json — configure CLI paths, Telegram bot, KB sources, port.
• cp examples/daily_todos.example.json data/daily_todos.json — daily checklist.
• python tg_bridge.py — Telegram remote control (needs bot token in config).
• Load flows/demo_daily_digest.json in the Canvas tab and hit Run for a fetch → summarize → approve → notify demo.

Architecture

cockpit.html (vanilla JS, single file)          your phone (Telegram)
        │  polling                                      │ buttons
        ▼                                               ▼
server.py (FastAPI, localhost) ◄──────────────── tg_bridge.py
   ├─ flow_engine.py   canvas graph → staged runs (toposort, parallel levels)
   ├─ approvals.py     SQLite approval inbox (first-wins, timeout-deny, audit)
   ├─ todos.py         daily checklist
   ├─ issues_store.py  local issue tracker
   ├─ sessions.py      Claude Code session discovery / rescue
   └─ kb.py            BM25 local search
runs/<id>/  events.jsonl + state.json + flow_snapshot.json + steps.json  (auditable)

Design notes: the canvas is just a view over a graph JSON (Step Functions philosophy); runs are append-only event logs (Temporal philosophy); approvals follow the HumanLayer/Agent Inbox model; retry follows n8n’s dual semantics. See docs/DESIGN.md.

Multi-engine roadmap

The “employee” abstraction is any CLI that supports headless prompts + session resume. Claude Code is first-class today; Codex runs as the red-team engine. Adapters for Gemini CLI, Kimi CLI, opencode, goose etc. are a thin provider layer — contributions welcome.

Status & caveats

• Single-user by design (loopback only, enforced). Multi-user needs auth/RBAC — deliberately not built until there is a second user.
• UI text is currently zh-TW-heavy (built for its original operator); i18n is a welcome contribution.
• Windows is the daily-driver platform. Core (server/canvas/approvals/todos) is portable; health scan and session relaunch are Windows-only today.

License

MIT © 2026 Hsien-Chu Chen. Bundled Drawflow © Jero Soler, MIT — see static/vendor/DRAWFLOW-LICENSE.

This site is open source. Improve this page.