ac7 claude-code

ac7 claude-code wraps a Claude Code session in a ac7 runner. The runner is the parent; claude is the child. You talk to claude in the same terminal you launched the runner from.

ac7 claude-code

If --token / $AC7_TOKEN aren’t set, the runner falls back to a saved ~/.config/ac7/auth.json entry for the resolved broker URL. Run ac7 connect first if you haven’t.

Synopsis

ac7 claude-code [--no-trace] [--doctor] [--skip-doctor] [--unsafe-tls]
                [--url <url>] [--token <secret>] [-- <claude args>...]

What it does on startup

1. Locate claude. Reads $CLAUDE_PATH first, falls back to which claude. Fails fast (no socket bind, no .mcp.json touch) if the binary is missing.
2. Run preflight. Unless --skip-doctor is set, runs the same four checks --doctor does, silently. WARN states proceed; any FAIL aborts and dumps the full report to stderr.
3. Start the runner. startRunner() fetches the briefing, binds the IPC socket, starts the SSE forwarder. Failures surface as a RunnerStartupError with an actionable hint (e.g. “is ac7 serve running at <url>?” on connection refused).
4. Start the trace host (unless --no-trace). Generates a fresh per-session local CA, writes the cert PEM to $TMPDIR/ac7-trace-ca-<pid>-<nonce>.pem at 0o600, binds the loopback CONNECT proxy on a random ephemeral port. The CA’s private key never touches disk.
5. Back up .mcp.json and write a fresh one. The current working directory’s .mcp.json is copied to a pid-scoped tmp path, then atomically rewritten with a ac7 MCP-server entry that spawns ac7 mcp-bridge against this runner’s socket. If no prior .mcp.json existed, a new one is created.
6. Auto-inject claude flags (see below).
7. Spawn claude. If node-pty is loadable and stdin/stdout are TTYs, the runner takes the pty path and reserves the bottom HUD_HEIGHT rows for the ac7 status strip. Otherwise it falls back to stdio: 'inherit' and skips the HUD.
8. Wait for claude to exit. On any exit path (normal, SIGINT, SIGTERM, uncaughtException, unhandledRejection): restore the original .mcp.json, shut down the runner, close the trace host, unlink the socket, delete the CA cert PEM.

The auto-injected claude flags

Three flags are always-on for ac7 sessions because they’re structural requirements rather than convenience. The runner injects them before any user-supplied claude args, and prints a banner to stderr listing what was injected so the posture is visible on turn 1.

If the user passes any of these themselves, the runner suppresses the equivalent injection (and the banner). The briefing snapshot is taken at startup — edits to the team config require restarting the runner to take effect.

ac7: auto-injected into claude invocation (team authority is the access control):
    --dangerously-skip-permissions
    --dangerously-load-development-channels server:ac7
    --append-system-prompt <ac7 briefing, 1843 chars>
      (pass either flag yourself to suppress this line)

Environment passed to the agent

When tracing is on, the trace host returns an env delta which the runner merges into claude’s environment:

HTTPS_PROXY=http://127.0.0.1:<ephemeral-port>
HTTP_PROXY=http://127.0.0.1:<ephemeral-port>
ALL_PROXY=http://127.0.0.1:<ephemeral-port>
NO_PROXY=localhost,127.0.0.1,::1,<caller's value>
NODE_USE_ENV_PROXY=1
NODE_EXTRA_CA_CERTS=$TMPDIR/ac7-trace-ca-<pid>-<nonce>.pem
NODE_OPTIONS=<existing> --loader <ac7 ssl-keylog loader>
SSLKEYLOGFILE=<runner-managed path>
AC7_RUNNER_SOCKET=/tmp/.ac7-runner-<pid>.sock

When --unsafe-tls is set, the runner also injects:

NODE_TLS_REJECT_UNAUTHORIZED=0

and prints a hard-edged warning box to stderr. Use this only when claude is a packaged binary that ignores NODE_EXTRA_CA_CERTS, and accept that all TLS validation is off in the agent process for the entire session. Loopback-MITM traffic going through our proxy is still validated against the real upstream — just not against our injected CA.

When --no-trace is set, none of these are injected; the runner sets only AC7_RUNNER_SOCKET.

The MCP bridge wiring

The runner detects the bridge command from its own process:

• bridgeCommand: process.execPath (the running node binary)
• bridgeArgs: [process.argv[1], 'mcp-bridge'] (this CLI’s entry script + the subcommand)

Baking these into .mcp.json means claude spawns the SAME cli that spawned it — no $PATH assumptions, works identically for global npm install, pnpm script, or development checkout. The bridge subprocess reads $AC7_RUNNER_SOCKET to find the runner’s IPC socket.

The .mcp.json shape written by the runner:

{
  "mcpServers": {
    "ac7": {
      "command": "/path/to/node",
      "args": ["/path/to/cli/dist/index.js", "mcp-bridge"],
      "env": {
        "AC7_RUNNER_SOCKET": "/tmp/.ac7-runner-12345.sock"
      }
    }
  }
}

Any pre-existing mcpServers entries are preserved (the runner merges, not replaces). On exit, the original file is restored byte-for-byte.

—doctor checks

ac7 claude-code --doctor runs four checks and prints a PASS / WARN / FAIL line for each:

Exit code is 0 if all checks PASS / WARN, 1 if any FAIL.

The default behavior (without --doctor or --skip-doctor) is to run these checks silently before spawn and dump the full report to stderr only if any FAIL. WARNs proceed quietly.

The HUD strip

When node-pty is available and stdin/stdout are TTYs, the runner relays claude’s output through a pty and reserves the bottom HUD_HEIGHT (5) rows for a status strip:

                   ┌──────────────────────────────────────────────┐
                   │                                              │
                   │            claude TUI (rows - 5)             │
                   │                                              │
                   ├──────────────────────────────────────────────┤
                   │ ac7  ⊙ online  ·  builder@ac7-team           │
                   └──────────────────────────────────────────────┘

The HUD shows presence (connecting → online → offline) plus the agent’s identity. It’s repainted after every chunk claude writes (so CSI 2J repaints don’t leave it stale) and on terminal resize. SIGWINCH is forwarded as pty.resize(cols, rows - HUD_HEIGHT) so claude’s renderer never paints into the strip.

When node-pty isn’t loadable (the package is in optionalDependencies so it may be absent on some platforms), the runner falls back to stdio: 'inherit' and skips the HUD. Sessions remain functional; only the strip disappears.

When stdin/stdout aren’t TTYs (tests, piped input), the runner also falls back to stdio: 'inherit' so automation stays byte-for-byte compatible.

First-render quirk on the pty path: claude-code’s ink fork blocks its first render on a terminal-capability probe whose reply doesn’t materialize under a relay. Press Enter once after the banner to unblock it; the keystroke is forwarded to claude as a no-op submit on the welcome prompt.

Pass-through args to claude

Anything the runner doesn’t recognize flows through to claude:

# These are equivalent:
ac7 claude-code --model claude-3-opus-20250219
ac7 claude-code -- --model claude-3-opus-20250219

The literal -- is optional but recommended for unambiguity when forwarded args might collide with future ac7 flags.

Session log

Every run writes structured JSON to a session log under ~/.cache/agentc7/:

~/.cache/agentc7/session-claude-code-<pid>.log

The path is printed on startup so you can tail -f it for live diagnostics. Each line is one event: runner state changes, IPC frames, MCP requests, trace uploads, broker errors. Stdout stays clean for claude; stderr is human-facing notices only.

Common patterns

# First-time on a new device
ac7 connect
ac7 claude-code

# Pinned model + extra claude args
ac7 claude-code --model claude-3-opus-20250219 -- --resume

# Quick sanity check before spawning
ac7 claude-code --doctor

# Skip preflight in a known-good environment
ac7 claude-code --skip-doctor

# Disable trace (debugging the runner/bridge plumbing)
ac7 claude-code --no-trace

# Packaged-binary Claude that can't honor NODE_EXTRA_CA_CERTS
ac7 claude-code --unsafe-tls