Metadata-Version: 2.4
Name: squadcue
Version: 0.1.0
Summary: Local-first mission control for CLI coding agents — flows, approval gates, run history, optional Telegram bridge.
Author: Hsienchu Chen
License: MIT License
        
        Copyright (c) 2026 Hsien-Chu Chen (hsienchuc)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/hsienchuc/squadcue
Project-URL: Repository, https://github.com/hsienchuc/squadcue
Project-URL: Issues, https://github.com/hsienchuc/squadcue/issues
Keywords: agents,claude-code,codex,orchestration,mission-control,fastapi
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Framework :: FastAPI
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: jieba>=0.42
Requires-Dist: rank-bm25>=0.2.2
Dynamic: license-file

# 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](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.

![Mission control: daily todos, approval inbox, live runs](docs/img/cockpit-ops.png)

| Flow canvas | Employees |
|---|---|
| ![Canvas](docs/img/cockpit-canvas.png) | ![Employees](docs/img/cockpit-employees.png) |

## 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](#immortal-employees-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](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](SECURITY.md).

## Quickstart

### pip install

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

> PyPI publication is pending (account setup) — until it lands, install straight from GitHub:
> `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

```bash
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](https://claude.com/claude-code) (primary), Codex CLI (optional red-team engine).

📖 **Full user manual: [docs/GUIDE.md](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](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](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](https://github.com/jerosoler/Drawflow) © Jero Soler, MIT — see `static/vendor/DRAWFLOW-LICENSE`.
