squadcue

SquadCue

Your AI CLI sessions, as employees — with an approval inbox for anything risky.

Every Claude Code session on your machine becomes a named contact you chat with, resume across restarts, and supervise from your phone. When an employee wants to run a shell command or write a file, the action pauses into an approval inbox (web + Telegram, first response wins, timeout = deny) until you say yes. A visual canvas orchestrates repeatable pipelines on top. Claude Code is first-class today; Codex ships as an optional red-team engine; other CLIs are a thin adapter layer away (see roadmap). A small FastAPI server + a one-file cockpit UI (plus one vendored library). No Docker, no database server, no build step. The control plane and its state stay on your machine (prompts go to your AI provider, as with any AI CLI).

Extracted in July 2026 from the tooling behind a real one-person operation that has run daily since early 2026 — research pipelines, content generation, daily ops.

Flow canvas	Employees

Why SquadCue

	SquadCue	n8n / Windmill / Dify	GitHub Agent HQ
AI CLI sessions as “employees” (named contacts, session 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 (plain JSON/JSONL + SQLite files, 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 SquadCue.

Features

• 💬 Employees — each Claude Code session is a contact: named, resumable (claude -p --resume, so memory persists as far as the session’s context does — durable cross-session memory is the roadmap), streaming replies. Session rescue relaunches any CLI window after a reboot.
• 🔒 Approval inbox — the safety core, wired to both halves of the product. In employee chat, “allow tools” routes risky actions (shell, file writes) through a PreToolUse hook into the inbox — read-only tools pass silently, everything else waits for you. On the canvas, gate nodes pause a flow the same way. Web + Telegram, first response wins, every decision audited, timeouts deny by default, never approve.
• 🎨 Canvas — drag-and-drop flow editor (Drawflow) for repeatable pipelines: action / claude / codex / gate / shell / fetch / tg / wait / readfile / writefile / kb nodes (swarm / tournament are experimental). Runs always execute the canvas you see; every run stores a snapshot of the flow definition + per-node inputs/outputs/duration.
• 🔁 Retry semantics (n8n-style) — re-run the original flow definition, or the current saved version (picks up fixes), with lineage tracking.
• 🩺 Run diagnosis — one click on any failed run dispatches a read-only agent that reads the run’s event log and reports probable cause + suggested fix; changes go through you.
• 📅 Morning push — recurring todo definitions feed a morning Telegram digest and .ics export via included scripts (ops/) you schedule yourself.
• 🔎 Local knowledge base primitive — BM25 search (CJK-friendly) over markdown folders, exposed as a canvas node.
• 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/squadcue && cd squadcue
python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
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).

📖 Full user manual: docs/GUIDE.md — every tab, the approval gate end-to-end, config reference, Telegram commands, FAQ.

Stock Debian/Ubuntu ships without pip/venv — run sudo apt install python3-pip python3-venv first. (Verified on a clean Ubuntu 24.04: after that, all 14 deps install with zero build errors and the cockpit serves at first try.)

Optional:

• mkdir -p data(Windows: md data)— runtime dir, auto-created on first server start.
• cp examples/squadcue.example.json squadcue.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. Full node reference: docs/CANVAS.md.

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.

Immortal employees (roadmap)

Sessions die when context fills up; employees shouldn’t. The next milestone flips the identity model: an employee is a directory, a session is just a shift.

• employees/<name>/ holds an identity card (CLAUDE.md) plus a layered memory (memory/MEMORY.md one-page index → topic files → BM25-searchable archive).
• The server tracks each employee’s context watermark from stream-json usage; past 70% it asks the outgoing shift to write a handoff state file in the background, then spawns a fresh session that boots from identity card + index + state + the last few turns — the operator never notices the swap.
• Boot cost stays constant (~2.5k tokens) no matter how old the employee gets: growth lives on disk, a monthly compaction job keeps the index one page, and the stable prefix rides prompt caching.

Status & caveats

• Single-user by design (loopback only, enforced). Multi-user needs auth/RBAC — deliberately not built until there is a second user.
• The open-source UI and logs ship in English (the original operator’s private variant runs in zh-TW); a proper i18n layer instead of hardcoded strings is a welcome contribution.
• Windows is the daily-driver platform. Core (server/canvas/approvals/chat) is portable; session relaunch is Windows-only today.
• Employee chat turns are single-shot headless runs. The CLI process ends when its reply ends, and any background job it spawned (&, nohup, detached shells) dies with it — an agent promising “I’ll run this in the background and report later” will silently lose the work. For long tasks: let the agent run them synchronously within the turn (a turn can run for many minutes), or have it write a standalone script and drive that from a Canvas flow shell node or your OS scheduler, with results written to a file the next turn can read. Learned in production the hard way.

License

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

This site is open source. Improve this page.