Commands Reference
cq CLI
Current version: v1.46
cq / cq claude
Launch Claude Code with CQ project initialization.
cq # Launch claude (no telegram)
cq -t <name> # Named session (fixed UUID via --session-id)
cq --bot # Show bot menu → connect telegram
cq --bot <name> # Connect specific telegram bot
cq -t <name> --bot <name> # Named session + telegramOther AI tools
cq cursor # Cursor
cq codex # OpenAI Codex CLI
cq gemini # Gemini CLIEach command creates CLAUDE.md, .c4/, skills, and the MCP config for that tool:
| Command | MCP config | Agent instructions |
|---|---|---|
cq claude | .mcp.json | CLAUDE.md |
cq cursor | .cursor/mcp.json | CLAUDE.md |
cq codex | ~/.codex/config.toml | .codex/agents/ |
cq gemini | (Gemini CLI config) | CLAUDE.md |
Any tool supporting the AGENTS.md standard (e.g. Gemini Code Assist) can read
CLAUDE.mddirectly without a dedicatedcqcommand.
cq doctor
Check environment health (13 items).
cq doctor # full report
cq doctor --json # JSON output (for CI)
cq doctor --fix # auto-fix safe issues| Check | What it verifies |
|---|---|
| cq binary | Binary exists + version |
| .c4 directory | Database files present |
| .mcp.json | Valid JSON + binary path exists |
| CLAUDE.md | File exists + symlink valid |
| hooks | Gate + permission-reviewer hooks installed |
| Python sidecar | uv available |
| Supabase Worker Queue | Supabase connection + worker queue health |
| Supabase | Cloud config + connection |
| os-service | LaunchAgent / systemd service installed and running |
| tool-socket | UDS socket responsive (cq serve running) |
| zombie-serve | No orphaned serve processes |
| sidecar | Python sidecar not hung |
| skill-health | All evaluated skills pass trigger threshold (≥ 0.90) |
cq update
Self-update CQ to the latest release.
cq update # Check and install the latest version
cq update --check # Check only, do not installcq secret
Manage API keys and secrets (stored in ~/.c4/secrets.db, AES-256-GCM).
cq secret set anthropic.api_key sk-ant-...
cq secret set openai.api_key sk-...
cq secret set hub.api_key <your-hub-key> # Worker queue API key (preferred over config.yaml)
cq secret get anthropic.api_key
cq secret list
cq secret delete anthropic.api_keyKeys are never stored in config files.
cq auth
Authenticate with C4 Cloud (GitHub OAuth).
cq auth login # Open browser for GitHub OAuth flow
cq auth logout # Clear stored credentials (~/.c4/session.json)
cq auth status # Show current authentication statuscq ls
List registered Telegram bots.
cq lscq sessions
List named Claude Code sessions.
cq sessionsExample output:
my-feature a07c5035 ~/git/myproject Mar 01 10:30
auth-fix 5a98a761 ~/git/myproject Feb 28 23:12 ✉2
data-work 869fd61e ~/git/data Feb 26 18:03
Analyzing training data pipeline✉Nshows unread inter-session mail count- Memo (if set) is displayed on the line below
cq session
Manage named Claude Code sessions.
cq session name <session-name> # Attach a name to the current session
cq session name <session-name> -m "memo" # Attach name with memo
cq session rm <session-name> # Remove a named sessionSessions can be resumed with cq -t <session-name>.
Use /attach inside Claude Code to name a session without leaving the editor.
cq mail
Inter-session mail for passing messages between Claude Code sessions.
cq mail send <to> <body> # Send a message to a named session
cq mail ls # List messages (shows unread count)
cq mail read <id> # Read a message (marks as read)
cq mail rm <id> # Delete a messagecq jobs
BubbleTea TUI for Hub job monitoring.
cq jobs # Open interactive job monitor
cq jobs --watch # Auto-refresh modeFeatures: detail panel with per-job metrics, adaptive multi-row charts, compare mode for side-by-side job diffs.
cq workers
Worker Connection Board TUI — view and manage connected Hub workers.
cq workers # Open worker boardShows worker status, heartbeat, current job assignment, and resource utilization per worker.
cq dashboard
Unified TUI dashboard with board menu — entry point for all monitoring views.
cq dashboard # Open dashboard (board menu → jobs / workers / pop / sessions)cq setup
Pair a Telegram bot for notifications.
cq setupWalks through Telegram bot pairing: enter your bot token, start the bot, and CQ auto-detects your chat ID. After setup, CQ sends experiment and task notifications via Telegram.
cq serve
Run background services (EventBus, GPU scheduler, Agent listener, Relay).
cq serve # start on :4140
cq serve --port 4141
cq serve --watchdog # OS service with watchdog: auto-restarts relay on failure, heartbeat self-healing
cq serve install # Install as OS service (macOS LaunchAgent / Linux systemd / Windows Service)
cq serve uninstall # Uninstall the OS service
cq serve status # Show OS service status and manual serve process statusWhen hub is enabled in config, the worker is automatically enabled alongside the hub.
Health endpoint: GET http://127.0.0.1:4140/health — returns status of all registered components.
# Check component health
curl http://127.0.0.1:4140/health
# {"status":"ok","components":{"eventbus":{"status":"ok"}}}cq pop
Personal Ontology Pipeline status and control.
cq pop status # Show gauge values, pipeline state, and knowledge statscq craft
Skill Marketplace — publish, search, and install community skills.
cq craft publish # Publish a skill to the marketplace
cq craft search # Search available skills
cq craft install # Install a skill from the marketplacecq version
Print the current binary version and build tier.
Skills (Claude Code slash commands)
Skills are invoked inside Claude Code as /skill-name.
| Skill | Trigger | Description |
|---|---|---|
/pi | "play idea", "idea", "ideation" | Brainstorm before planning; auto-launches /plan |
/plan | "plan", "planning", "design" | Discovery → Design → Tasks |
/run | "run", "execute", "go" | Spawn workers for pending tasks |
/finish | "finish", "complete", "wrap up" | Build → test → docs → commit |
/status | "status", "progress" | Visual task progress |
/quick | "quick", "fast" | Single task, no planning |
/polish | "polish" | (Deprecated — built into /finish) |
/refine | "refine" | (Deprecated — built into /finish) |
/checkpoint | checkpoint reached | Approve / request changes / replan |
/validate | "validate", "check" | Run lint + tests |
/review | "review" | 3-pass code review with 6-axis evaluation |
/company-review | "code review", "diff review" | PI Lab standard code review |
/submit | "submit", "send" | Submit completed task |
/simplify | "simplify", "clean up" | Review changed code for quality and efficiency |
/add-task | "add task" | Add task interactively |
/stop | "stop", "halt" | Halt execution, preserve progress |
/clear | "clear" | Reset C4 state for debugging |
/swarm | "swarm" | Spawn coordinator-led agent team |
/standby | "wait", "standby" | Become a distributed worker via Supabase (full tier) |
/done | "done", "session end" | Mark session done with full capture |
/attach | "session name", "attach" | Name the current session for later resume |
/reboot | "reboot", "restart" | Reboot the current named session |
/session-distill | "session distill", "session summary" | Distill session into persistent knowledge |
/init | "init", "initialize" | Initialize C4 in current project |
/release | "release" | Generate CHANGELOG from git history |
/help | "help" | Quick reference for all skills |
/claude-md-improver | "improve CLAUDE.md" | Analyze and improve CLAUDE.md |
/skill-tester | "skill test", "skill eval" | Test and evaluate skill quality |
/pr-review | "create PR", "PR checklist" | PR/MR creation checklist and review guide |
/craft | "craft", "create skill" | Interactively create skills, agents, rules |
/tdd-cycle | "TDD", "RED-GREEN-REFACTOR" | TDD cycle guide |
/debugging | "debug", "debugging" | Systematic debugging workflow |
/spec-first | "spec-first", "design doc" | Spec-First development guide |
/incident-response | "incident", "outage", "server down" | Production incident response workflow |
/c2-paper-review | "paper review", "academic review" | Academic paper review (deprecated) |
/research-loop | "research loop" | Paper-experiment improvement loop |
/experiment-workflow | "experiment workflow" | End-to-end experiment lifecycle |
/c9-init | "c9-init" | Initialize C9 ML research project |
/c9-loop | "c9-loop" | Main loop driver for ML research |
/c9-survey | "c9-survey" | Survey arXiv + SOTA with Gemini |
/c9-conference | "c9-conference" | Claude + Gemini research debate |
/c9-steer | "c9-steer" | Phase transition without editing YAML |
/c9-report | "c9-report" | Collect remote experiment results |
/c9-finish | "c9-finish" | Save best model + document |
/c9-deploy | "c9-deploy" | Deploy best model to edge server |