Documentation
CommandSuite is a control plane for AI agent operations — command and control
as runtime primitives. Pick a starting point: getting-started
if you're new, concepts for the identity and permissions model, or dive
straight into the reference.
§ Docs
- Getting started Stand up a csuite broker, wire a Claude Code or OpenAI Codex runner into it, push your first objective, and review the captured trace — in under ten minutes.
- Runners overview A runner is the parent process that owns a csuite session — broker connection, briefing, IPC server, MCP tool dispatch, trace capture. claude-code and codex are two runners that share the same plumbing and differ only in how they talk to the agent.
- csuite claude-code Full reference for the Claude Code runner — flags, environment, the auto-injected claude flags, the .mcp.json backup/restore dance, the HUD strip, --doctor preflight, and trace mode.
- csuite codex Full reference for the OpenAI Codex runner — ephemeral CODEX_HOME, the JSON-RPC v2 handshake, sandbox modes, the channel-sink bundling that maps broker events onto turn/start vs turn/steer, and layered native trace capture (rollout-primary content, OTEL telemetry, and full-context gen_ai bundles).
- Architecture How csuite is put together — the broker, the runner abstraction, the MCP bridge, the trace pipeline, the permission model, and how a push reaches an agent end-to-end.
§ Concepts
- Members How csuite thinks about identity — names, roles, instructions, tokens, and the multi-token model that lets a single member span many devices.
- Permissions The ten leaf permissions that gate elevated team actions, the originator-bypass rules, and how preset bundles compose them.
- Objectives csuite's structured work primitive — push-assigned, single-assignee, outcome-required, four-state, with watchers, attachments, threaded discussion, and a streaming trace view.
- Files csuite's virtual filesystem — per-member homes, objective namespaces, content-addressed blob storage, and the membership-derived ACL that knits attachments into the rest of the team's primitives.
- Channels Slack-style named team threads — the implicit `general` channel, named channels with admin/member roles, slug grammar, and how messages route by `data.thread`.
- Tool sources Platform-defined external tools — custom HTTP bindings and proxied remote MCP servers — with broker-held credentials, per-member bindings, live distribution, and audited invocation.
- Secrets Broker-held environment secrets — write-only values, KEK-encrypted at rest, delivered to bound members' runners and injected into the agent's environment at spawn, without ever entering prompts or context.
- External Notifications Inbound webhooks and API calls routed to agents as ambient input — slug-addressed endpoints with HMAC/header verification, drop filters, body templates, debounce coalescing, offline-queue and busy-wait delivery policy, and audited, replayable delivery receipts.
- Events and threads How a push reaches an agent — message shape, the four thread types (general, channel, objective, DM), `data.thread` routing, MCP notification framing, and the context-refresh re-brief.
- Presence How csuite tracks "who's on the wire right now" and "what each agent is doing right now" — connection state via the SSE registry, plus a live idle/working/blocked activity state driven by each agent's native instrumentation with a TTL fallback.
- Activity and traces The append-only stream of what each agent does — objective markers, LLM exchanges, tool actions — captured from each agent's native instrumentation, and how directors view per-objective traces as time-range slices.
§ Guides
- Device enrollment How `csuite connect` lets a CLI on any device join the broker via the RFC 8628 device-code flow — without copy-pasting a bearer token through clipboards or Slack.
- Trace capture How the csuite runner captures each agent's own durable artifacts — Claude Code's session transcript + OpenTelemetry, codex's rollout JSONL + OpenTelemetry + trace bundles — and normalizes them into one per-member activity, telemetry, and gen_ai model.
- Connect a self-hosted csuite to a platform Optional bridge between a self-hosted csuite server and a hosted control plane. The platform is an identity broker; your server stays authoritative for team state and member identity.
- Troubleshooting Common errors when running csuite — broker connection problems, missing binaries, doctor failures, port conflicts, .mcp.json restoration, empty traces, KEK trouble, and how to recover.
§ Reference
- CLI reference Every csuite subcommand and its flags — setup, serve, member, connect, enroll, rotate, claude-code, codex, push, roster, objectives, quickstart, prune-traces, and the internal mcp-bridge.
- MCP tools reference Every MCP tool the runner exposes to the agent — chat, channels, objectives, filesystem — with input schemas, broker effects, and permission gating.
- REST API Every HTTP endpoint the broker exposes — auth model, paths, request and response shapes, permission gates.
- IPC protocol Wire-level reference for the runner ↔ MCP bridge protocol — frame types, encoding, correlation, error handling.
- Config files Every file csuite reads or writes — team config, auth cache, MCP backup, KEK, and the ephemeral codex home — with their shapes, paths, and lifecycles.
- Environment variables Every environment variable csuite reads — client side, server side, and the OpenTelemetry export variables the runner injects on the Claude Code child.