ClaudEquip Switchboard

Persistent external CLI workers for AI coding agents. Dispatch tasks to long-lived tmux sessions with event-driven completion signals.

Works on Claude Code, GitHub Copilot CLI, and Codex CLI.

What It Does

• Keeps external CLI workers (Codex, Claude CLI, Gemini, any binary) alive across tasks — no cold-start penalty
• Routes work by intent via policy-layer task classes (fast/balanced/deep/review/external)
• Event-driven completion signals (inotifywait/fswatch/node) — no polling
• Watchdog auto-restarts crashed workers and re-delivers pending tasks

Quick Start

Prerequisites

• tmux — worker session management
• jq — config parsing
• inotifywait (Linux) or fswatch (macOS) — signal detection (falls back to node)
• An external CLI worker binary (codex, claude, gemini, etc.)

Install

Clone into your project or as a standalone plugin:

git clone https://github.com/HuuDoe/ClaudEquip.git .claude-plugins/claudequip

Or add to an existing project:

# The .claude-plugin/plugin.json is auto-detected by Claude Code and Copilot CLI

Usage

# Dispatch a task to the persistent worker
bash scripts/dispatch.sh "refactor the authentication module"

# Check worker status
bash scripts/worker.sh status

# Wait for completion (called automatically by dispatch command)
bash scripts/wait-for-signal.sh

# Stop the worker
bash scripts/worker.sh stop

Via slash command (when loaded as a plugin):

/claudequip:dispatch refactor the authentication module

Architecture

.claude-plugin/plugin.json       # Plugin manifest (Claude Code + Copilot CLI)
commands/dispatch.md             # /claudequip:dispatch slash command
scripts/
  dispatch.sh                    # Task creation + delivery
  worker.sh                     # Persistent worker lifecycle (start/stop/status/send)
  wait-for-signal.sh            # Event-driven completion wait + watchdog
templates/
  task.md.tmpl                   # Task file template (YAML frontmatter)
  config.json.tmpl               # Default provider config

Runtime State (.switchboard/, gitignored)

.switchboard/
  config.json                    # Provider config (binary, flags, safety)
  tasks/                         # Task files (task-001.task.md, ...)
  signals/                       # Completion signals (task-001.done.json, ...)
  state/                         # Worker state (pane-id, last-task-id, ...)

Configuration

Copy and edit the default config:

cp templates/config.json.tmpl .switchboard/config.json

{
  "provider": {
    "name": "codex",
    "binary": "codex",
    "flags": ["--full-auto"]
  },
  "safety": {
    "sandbox_bypass": false
  }
}

Platform Support

Feature	Claude Code	Copilot CLI	Codex CLI
Plugin auto-load	Yes	Yes	No
Slash commands	Yes	Yes	No
Skills/Agents	Yes	Yes	Yes
Hooks	Yes	Yes (different events)	No

Codex CLI uses skills (~/.codex/skills/) — an adapter layer bridges the gaps for hooks and commands.

Security

• No shell injection — printf '%s' / awk -v / positional $@, never string interpolation
• Atomic task IDs — set -o noclobber prevents TOCTOU races
• Signal verification — accept_done() validates taskId field before accepting completion
• Restricted permissions — chmod 0700 on all runtime directories
• Temp file cleanup — trap EXIT in every script
• Configurable binaries — validated with command -v, never hardcoded

Project Status

Phase 1: Core Dispatch — complete, security-hardened, watchdog-enabled

Upcoming:

• Phase 2: Setup skill, routing logic, status/stop commands
• Phase 3: Copilot CLI cross-platform smoke test
• Phase 4: Stop hook for persistence enforcement

See docs/SWITCHBOARD-PRD.md for the full plan.

License

MIT