subctl

An agentic harness for the AI subscriptions you already pay for.

A persistent conversational orchestrator that runs on your hardware, talks to you through a dashboard chat panel or Telegram, spawns dev-team tmux sessions on demand, watches them for staleness, gates its own claims with a runtime verifier, and pushes projects forward — with your laptop closed and your subscriptions on auto-rotate.

                                     ┌─────────────────────────┐
                                     │  subctl master          │
   you ─────────────┐                │  (persistent daemon)    │
                    │                │                         │
   dashboard chat ──┼──────────────► │   • SKILL + tier-1 mem  │
   Telegram     ────┘                │   • 50+ tools           │
                                     │   • Verifier + watchdog │
                                     │   • Personality presets │
                                     │   • Scheduler           │
                                     └─────────┬───────────────┘
                                               │  spawn / msg / kill
                                               ▼
                                     ┌─────────────────────────┐
                                     │  dev teams (tmux)       │
                                     │   • Claude Code workers │
                                     │   • per-account isolate │
                                     │   • own SKILL + tools   │
                                     └─────────────────────────┘

v2.6.0 shipping. Full per-release history in CHANGELOG.md. The 1.x series was the multi-account dispatch substrate; the 2.x series is the agentic harness layered on top.

🚀 First time on a new Mac? Open a fresh Claude Code session and paste START-HERE.md. It walks you clone → install → account auth → master daemon enable, asking before any irreversible step.

---

What you actually get

• Conversational dev-team orchestrator — talk to subctl master in the dashboard chat or Telegram. It spawns Claude Code workers in tmux sessions on the right accounts, watches them for staleness, nudges or escalates as needed. Responses route back to whichever channel you used.

• Multi-account dispatch — run multiple Claude accounts + an OpenAI Codex OAuth account on one machine without log-out/log-in dances. The dispatcher picks the healthiest account (lowest rate-limit pressure) at spawn time.

• Three-tier memory:

  • Tier 1: user.md + memory.md always injected into the master's system prompt (~3500 char budget — fast, durable, operator-editable)
  • Tier 2: claude-mem semantic search over every dev-team observation
  • Tier 3: Obsidian vault for long-form decisions, specs, RESUME files — browse in-page via the built-in viewer with [[wikilinks]], embeds, callouts, and tag rendering

• Runtime claim verifier (Argent-style) — after every assistant turn the runtime scans for "claim triggers" (specific future check-in times, asserted team statuses, host facts, sent-message claims, decision-logged claims). Any claim not backed by a tool call this turn fires a synthetic [verifier] correction prompt. Capped at 2 corrections; on giveup the gap lands in decisions.jsonl so you can grep chronic offenders.

• Self-scheduling — when the master says "I'll check in 15 minutes" it MUST call schedule_followup first or the verifier catches the unbacked promise. The followup record survives daemon restarts.

• Multi-team camera view — NVR-style grid of every active dev-team tmux pane in the Orchestration tab, polling at 2 Hz. Click a tile to expand to full pane.

• Document attachments in chat — drag-drop a file, click the paperclip, or paste >4 KB to auto-attach. The chat surface stays readable (pill chips) while the model sees full inline content. After auto-compaction the master can re-read via the read_attachment tool.

• Personality presets — hot-swap the master's voice (straight-shooter, witty, sarcastic, robotic, arnold-inspired, elon-inspired, hilarious) without touching its persona contract. CLI + dashboard tile.

• Watchdog + auto-compact — master ticks every 3 min; if any team has gone silent past the staleness threshold (15 min default), it synthesizes a corrective prompt. Auto-compact runs every 5 min, compacting transcript history when it crosses 90 % of the supervisor's loaded context window.

• Dashboard — live ops view at http://<host>:8787 with 12 sidebar tabs (Chat, Orchestration, Dashboard, Projects, Teams, Claude Sessions, Models, Providers, Memory, Vault, Skills, Live Logs, Settings).

• Multi-channel I/O — dashboard chat (SSE), Telegram (bidirectional with auto-relay), CLI prompt, scheduled self-prompts, inbox events from workers.

---

Install

git clone https://github.com/webdevtodayjason/subctl.git
cd subctl

# 1. See what's missing without touching anything (recommended first step)
bash install.sh --check-only

# 2. Run the full installer (preflight → install → verify → wire)
bash install.sh

The installer reads its full dep matrix from lib/dep-manifest.json (the single source of truth shared with subctl doctor, subctl setup --check, and the dashboard's Settings → Install Checks panel — edit one file, all four stay in sync).

Three phases:

1. Preflight — prints a status table of every hard + soft dep. No side effects.
2. Install — topologically ordered: Homebrew (auto-bootstrap if missing) → brew packages (jq, tmux, gh, gum, go, node) → bun (curl installer with BUN_INSTALL_NO_PROFILE=1) → claude CLI → codex → coderabbit → docker (cask, confirm) → claude-mem (npx) → Telegram bot walkthrough. Every step is confirm-gated unless --yes is passed.
3. Verify — re-runs preflight, prints a final go/no-go table, then wires the Claude statusline + Stop hook + skills + MCP server + master daemon + dashboard service.

Auto vs. manual vs. detect-only:

Dep	How
Homebrew, jq, git, tmux, gh, node, gum, go	Auto via brew install
bun	Auto via curl https://bun.sh/install (with BUN_INSTALL_NO_PROFILE=1)
claude	Auto via curl https://claude.ai/install.sh
codex	Auto via npm i -g @openai/codex
coderabbit	Auto via curl https://cli.coderabbit.ai/install.sh
Docker Desktop	Auto via brew install --cask docker (confirm) — open the app once after install for system-extension prompts
claude-mem (Claude Code plugin)	Auto via npx --yes claude-mem install
LM Studio, Obsidian, Context7 key	Detect-only — manual install link printed, never auto-installed
Telegram bot	Walkthrough — see below

LM Studio default model. After LM Studio + lms are both detected, the installer offers to pull qwen/qwen3.6-35b-a3b (~20 GB) via lms get … with a Y/n confirm. Default is yes — subctl master can't supervise without a model loaded.

BotFather walkthrough. subctl master enable hard-aborts if ~/.config/subctl/master-notify.json is missing. The installer offers an interactive walkthrough for the @BotFather → token → chat_id → write config dance. Run it standalone any time:

bash install.sh --botfather       # or: subctl setup --botfather

Useful flags:

bash install.sh --check-only          # preflight + verify; NO installs
bash install.sh --skip-deps           # jump to component wiring
bash install.sh --yes                 # non-interactive; assume yes everywhere
bash install.sh --allow-missing-hard  # don't abort on missing hard deps
bash install.sh --botfather           # JUST the Telegram walkthrough
bash install.sh --dry-run             # show what would happen

Idempotent. Re-running on a fully-installed machine prints the ✓ table and skips the install phase entirely.

Add accounts to ~/.config/subctl/accounts.conf then run subctl install again — per-account isolation model is documented in docs/multi-account.md.

---

Daily ops

# Bring up the master + dashboard (launchd; auto-start at login)
subctl master enable
subctl install                            # also installs dashboard service

# Talk to master from the CLI
subctl master prompt "spec the foothold-v3 polish and spawn a team for it"

# Or just open the dashboard
open http://127.0.0.1:8787

# Spawn a dev team directly (bypass master)
subctl teams claude -a claude-jason -c ~/code/myproject -o -y

# Switch master's voice
subctl master personality set sarcastic

# Bounce the daemon if it got wedged
subctl master restart
subctl master kick                        # recover from launchd throttle (local TTY only)

# Pull latest + restart services
subctl update

# Status
subctl status                              # global verdict + accounts table
subctl doctor                              # tools + credentials + paths
subctl master status                       # daemon health + tools loaded + supervisor
subctl orch list                           # running dev-team tmux sessions

Full CLI surface: subctl help. Cheat sheet at http://<host>:8787/cheat. Full reference at http://<host>:8787/help.

---

Architecture

The canonical architecture document is docs/master.md:

• §1 Mental model — master as a conversational dev-team orchestrator
• §2 Components & file layout — daemon, dashboard, skills, templates, inbox
• §3 Memory architecture — the three tiers
• §4 Roadmap — every shipped phase + what's queued
• §5 Operational reference — restart cookbook, LM Studio config, accounts
• §6 Glossary
• §7 Decision log

Provider plugin model (how new AI subscriptions get wired in): docs/adding-a-provider.md. Release / bump policy: docs/release-workflow.md.

---

Repo layout

.
├── bin/subctl                     CLI entry point
├── components/master/             master daemon (Bun + pi-agent-core)
│   ├── server.ts                  HTTP, SSE, ticker scaffolding
│   ├── tools/                     50+ tools across 13 families
│   ├── personalities/             voice presets
│   ├── verifier.ts                runtime claim verifier
│   ├── attachments.ts             chat attachment storage
│   └── personality.ts             preset loader
├── components/skills/             baseline + master skills
│   ├── master/SKILL.md            master's own system prompt
│   ├── subctl/SKILL.md            worker-facing subctl skill
│   ├── autonomy/SKILL.md          worker autonomy doctrine
│   └── orchestrator-mode/SKILL.md anti-deadlock activation guard
├── dashboard/                     web UI (Bun static + SSE proxy; no build step)
│   ├── server.ts                  HTTP + WS + SSE + auto-proxy /api/master/*
│   ├── public/                    HTML/CSS/JS
│   └── help.md                    /help page source
├── providers/claude/              Claude Code provider (auth, teams, hooks, skills)
├── providers/openai/              OpenAI Codex provider (OAuth + device-auth)
├── lib/                           shell helpers (accounts, install, update,
│                                   master, plugins, settings, …)
├── docs/                          design docs (master.md, multi-account.md,
│                                   release-workflow.md, foothold links)
└── VERSION                        single source of truth for version

---

Roadmap

Per-phase status lives in docs/master.md §4. Headline:

• Phase 3a–3j (v2.0.0) — master daemon, 13 tool families, 3-tier memory, dashboard, verifier, auto-compact
• Phase 3k (v2.2.0) — personality presets
• Phase 3l (v2.4.0) — document attachments in chat
• Phase 3m (v2.3.0) — multi-team camera view
• Phase 3n (v2.5.0) — in-browser Obsidian vault viewer
• Phase 3o — baseline Claude config in repo (skills shipped in v2.1.0; permissions defaults + sub-agents still need sanitization pass)
• Phase 3p — Personal Skills System (ArgentOS-style operator UI)
• Phase 3q — Vault editor (CodeMirror 6 + Excalidraw canvas)

Provider expansion (Phase 4+): Gemini, Z.AI GLM, Minimax — see ROADMAP.md.

---

Contributing

PRs welcome. To add a new provider, read docs/adding-a-provider.md. For master daemon changes, read docs/master.md first — it has 3+ months of decision history baked in. For everything else, open an issue first so we can agree on shape.

Bump policy in docs/release-workflow.md: patch (Z) is the default; minor (Y) only for genuine new user-visible features; major (X) only for breaking changes. Single source of truth for the version is VERSION.

License

MIT — see LICENSE.