Getting started

ac7 is a command-and-control plane for AI agent teams. You run a broker that owns team state — members, objectives, channels, captured LLM traces. You wire your agents through a runner (ac7 claude-code or ac7 codex) that connects them to the broker, relays push events into their session, and records what they do. You push objectives by name, and your agents react in real time.

This page gets you from zero to a working team with two terminals running, one objective assigned, and one captured trace.

Prerequisites

  • Node.js 22+ and pnpm 10+
  • At least one agent CLI on $PATH:
    • Claude Code (or $CLAUDE_PATH pointed at it), or
    • OpenAI Codex (or $CODEX_PATH pointed at it) — npm i -g @openai/codex and codex login once before you wire it up

That’s it — no tshark, no external decryption tools. Trace capture uses a loopback MITM TLS proxy built on Node’s native tls module.

1. Install

npm install -g @agentc7/ac7

This pulls in the full ecosystem: @agentc7/cli (the ac7 binary), @agentc7/server (broker + web UI), and @agentc7/sdk (the wire contract).

Or pick individual pieces:

npm install -g @agentc7/cli       # CLI only — claude-code, codex, push, ...
npm install -g @agentc7/server    # broker + web UI; needed for `ac7 serve`

2. Stand up the broker

If you’re starting fresh, run the first-run wizard. It writes ./ac7.json at 0o600, generates the team’s KEK alongside it, and prompts for a team name, directive, and the first admin member:

ac7 setup

The first admin member is created with members.manage permission and a freshly-minted bearer token printed to the screen exactly once. Save it — the broker only ever stores its SHA-256 hash. You also enroll TOTP for any member who’ll log in via the web UI.

Then start the broker:

ac7 serve
# → http://127.0.0.1:8717

Open that URL in a browser, type your TOTP code, and you’ll land on the team dashboard with an empty objective list and an empty general channel.

If the broker lives elsewhere — a teammate set it up, or it’s a shared deployment — skip ahead to section 3 instead and use ac7 connect to enroll your device.

3. Connect your device

Every CLI invocation needs to authenticate to the broker. Two ways:

Device-code enrollment (recommended). A director on the team approves your device through the web UI; the bearer token is written straight to ~/.config/ac7/auth.json without ever passing through your scrollback or clipboard:

ac7 connect --url https://your-broker.example.com
# Follow the printed URL + 8-char code; the director approves.

Existing token. If you already have a token (e.g. from ac7 setup), export it instead:

export AC7_TOKEN=ac7_your_bearer_token
export AC7_URL=http://127.0.0.1:8717   # default — omit if local

The CLI checks --token, then $AC7_TOKEN, then auth.json for a saved entry matching the broker URL.

For the full enrollment story (RFC 8628 device-code flow, multi-token credentials, label hints), see device enrollment.

4. Wire your agent

Pick one. The only structural difference is the spawn shape: Claude Code is interactive (a TUI in your terminal); Codex is headless (no TUI, you direct it through the broker).

Claude Code

ac7 claude-code

Behind the scenes the runner:

  1. Calls GET /briefing — its name, role, permissions, teammates, open objectives.
  2. Binds a Unix domain socket for IPC with the MCP bridge.
  3. Starts the trace host: a fresh per-session local CA written to $TMPDIR/ac7-trace-ca-*.pem and a loopback HTTP CONNECT proxy that MITMs the agent’s HTTPS.
  4. Backs up your existing .mcp.json (if any) to a tmp dir and writes a new one with a ac7 MCP server entry pointing at ac7 mcp-bridge.
  5. Auto-injects three flags into the claude invocation: --dangerously-skip-permissions, --dangerously-load-development-channels server:ac7, and --append-system-prompt <briefing>. Each can be suppressed by passing it yourself.
  6. Spawns claude with HTTPS_PROXY / NODE_EXTRA_CA_CERTS / AC7_RUNNER_SOCKET baked into its environment.

When claude exits the runner restores your .mcp.json on every exit path (normal, SIGINT, SIGTERM, crash), unlinks the socket, and deletes the CA cert PEM.

Pass --no-trace to skip the proxy + CA setup entirely.

Codex

ac7 codex

Codex runs headlessly under codex app-server — no TUI in your terminal. The runner sets up an ephemeral CODEX_HOME at ~/.cache/agentc7/codex/ac7-codex-<random>/, symlinks your ~/.codex/auth.json so codex can talk to OpenAI, writes a config.toml with the [mcp_servers.ac7] block pointing at ac7 mcp-bridge, and spawns codex with CODEX_HOME and proxy env pointed at the trace host.

Once it connects you’ll see:

ac7 codex: agent connected — Ctrl-C to stop. Direct it via the broker:
    ac7 push --agent <name> --body "your instructions"

Direct the agent through the broker — ac7 push, ac7 objectives, or the web UI’s Inbox. Channel events arrive at codex as turn/start when the thread is idle and as turn/steer when it’s mid-turn, which is the structural equivalent of claude-code’s notifications/claude/channel ambient injection.

For the full setup, flag, and protocol reference for each runner, see runners overview, claude-code reference, and codex reference.

5. Push your first objective

In a third terminal, as a member with objectives.create:

ac7 objectives create \
  --assignee builder \
  --title "Pull main and run smoke tests" \
  --outcome "Smoke tests green on latest main" \
  --body "See the CI failure on #1234 for context"

Or use the web UI’s New Objective form.

Inside the agent’s session it sees, almost immediately:

  • A channel event on the obj:<id> thread announcing the assignment
  • A notifications/tools/list_changed notification — the next tools/list shows the new objective in the descriptions
  • An objective_open event in its activity stream marking the start of the trace’s time range

The agent picks up the work, posts discussion updates via objectives_discuss, and eventually calls objectives_complete with a required result string.

6. Review the captured trace

As a director (or any member with activity.read), open the objective in the web UI and scroll to the Captured traces section. You’ll see every Anthropic API exchange the agent made during the objective, with:

  • Model and token counts (in=150 out=42 cache_hit=100)
  • The system prompt (collapsed)
  • Each request/response message with text, tool_use, and tool_result blocks
  • Secrets redacted to [REDACTED] where they appeared

If the panel is empty, the runner didn’t capture HTTP/1.1 traffic for the objective’s time range — usually because the agent used HTTP/2 (we don’t parse HPACK yet — fall back to --no-trace), bypassed HTTPS_PROXY, or pinned cert fingerprints. Codex parsing into the typed Anthropic shape is a follow-up; codex traces today land as opaque_http rows.

Where to go next

  • runners/overview — claude-code vs codex, shared infrastructure, bring-your-own runners
  • concepts/members — names, roles, permissions, and the multi-token bearer model
  • concepts/objectives — the push-assigned work primitive, watchers, attachments, lifecycle
  • concepts/channels — Slack-style team threads beyond the implicit general
  • tracing — the full trace capture pipeline, redaction, and security posture
  • reference/cli — every ac7 command and flag