squadcue 0.1.1

Local-first mission control for CLI coding agents — flows, approval gates, run history, optional Telegram bridge.

SquadCue

Your AI CLI sessions, as employees — chat, resume, orchestrate, and gate risky tool calls through an approval inbox.

Recent Claude Code sessions on your machine become named contacts you chat with, resume across restarts, and supervise from your phone. In gated chat (the default when you allow tools), a shell command or file write pauses into an approval inbox (web + Telegram, first response wins, timeout = deny) until you say yes — and clearly labeled opt-outs ("Skip approvals", the New-task "Allow tools" box, canvas allow_tools, the Telegram ! prefix) bypass the gate on purpose. The inbox is a supervision workflow for a trusted local setup, not a security boundary — SECURITY.md spells out exactly what it does and does not stop. 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 — 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 — recent real Claude Code sessions (by default: last 21 days, conversation-sized files, up to 40) become contacts: 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. Discovery runs only after you consent on first launch. Session rescue reopens Claude Code sessions after a reboot (one-click on Windows; copy-paste command elsewhere).
• 🔒 Approval inbox — a supervision workflow wired through employee chat, issue dispatch, and self-heal. With "allow tools" on, a PreToolUse hook routes risky actions (shell, file writes, network fetches) into the inbox — a small list of local read/query tools passes silently, everything else waits for you and shows its full payload before you decide. On the canvas, gate nodes pause a flow the same way. Web + Telegram buttons, first response wins, decisions are recorded in the approvals table, and a timeout resolves to deny. Approving a shell command approves the whole program it runs — see SECURITY.md for what this mechanism cannot protect against.
• 🎨 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 flow run stores a snapshot of the flow definition + per-node inputs/outputs/duration.
• 🔁 Retry semantics (n8n-style) — re-run the snapshotted flow definition, or the current saved version (picks up fixes), with lineage tracking. Reruns execute the same definition; live inputs (URLs, files, model outputs) may differ between runs.
• 🩺 Run diagnosis — one click on any failed run dispatches a diagnosis agent launched with Claude's plan permission mode (the strongest read-only control the CLI exposes — an upstream control, not a sandbox); it reports probable cause + suggested fix, and changes go through you. The separate Self-heal button dispatches a fix agent whose risky actions pass through the approval inbox.
• 📅 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

pip install

pip install squadcue
squadcue                  # → http://127.0.0.1:8899

Prefer the bleeding edge? pip install git+https://github.com/hsienchuc/squadcue

squadcue creates its workspace (data/, runs/, flows/ with the demo flow, example configs) in ~/.squadcue on first run. --here uses the current directory instead, --dir PATH any other; --port / --host override the defaults. Drop a squadcue.json in the workspace to configure CLI paths, Telegram, KB sources.

git clone

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 once on a clean Ubuntu 24.04: after that, the requirements installed with zero build errors and the cockpit served 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 (all runs); flow_snapshot.json + steps.json (flow runs)

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. The server, approvals, and chat run elsewhere too, but the canvas shell node executes via PowerShell and session relaunch is Windows-only today — on stock Linux/macOS expect to adapt those pieces.
• Employee chat turns are single-shot headless runs. The CLI process ends when its reply ends, and background jobs it spawned (&, nohup, detached shells) generally die with it — the server waits only on the CLI process and does not manage process groups, so a truly detached process may survive; rely on neither. An agent promising "I'll run this in the background and report later" is likely to 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.