ai-agent/sidecar

claude-sidecar

A tiny host-side FastAPI wrapper that launches claude -p sessions on behalf of the ai-agent viewer.

Why a host process (not a container)

The ai-agent viewer runs in Docker and can't reach the host's claude CLI — its auth (~/.claude/.credentials.json), RTK/vault hooks, and skills all live in the host user's home. This sidecar runs natively on the host as the repo owner, so a session it spawns is exactly like one started from a terminal.

Flow

Frontend (sticky input)
   │  POST /api/spawn {prompt}
   ▼
ai-agent backend (container)
   │  generates a session UUID, POST /spawn to the sidecar
   ▼  http://host.docker.internal:8790/spawn   (Bearer SIDECAR_TOKEN)
claude-sidecar (host)
   └─ claude -p <prompt> --session-id <uuid> --output-format json \
              --permission-mode bypassPermissions --model opus \
              --remote-control   (detached)

--remote-control is added by default so every spawned run registers with Claude Code Remote Control and shows up in the Claude app — you can watch and drive the conversation from your phone. Set SIDECAR_REMOTE_CONTROL=0 to opt out.

Claude writes its transcript to ~/.claude/projects/-home-gabrielvidal-homelab/<uuid>.jsonl, which the ai-agent container already watches read-only. The new conversation appears in the viewer within ~2s and the frontend redirects to it once it has synced.

The conversation view has a matching sticky composer that continues an existing thread: it POSTs /api/spawn's sibling /api/resume, which the backend proxies to POST /resume here — claude -p <prompt> --resume <sessionId> in the session's original cwd. Because resume reuses the session id, the new turns append to the same transcript and stream straight into the open conversation.

Install (host)

sidecar/install.sh

Creates a venv, writes a systemd user unit (~/.config/systemd/user/claude-sidecar.service), and starts it. Reboot survival needs sudo loginctl enable-linger $USER.

Config comes from the repo .env: SIDECAR_TOKEN, SIDECAR_PORT (default 8790). The ai-agent container reads SIDECAR_URL + SIDECAR_TOKEN (see its docker-compose.yml, which also adds host.docker.internal:host-gateway).

Endpoints

• GET /health → {ok, cwd, claude, accounts, defaultAccount}
• GET /accounts (Bearer auth) → each account's claude auth status (loggedIn, email, orgName, subscriptionType), cached 60s, plus the pendingLogin below when one is waiting.
• POST /accounts/{id}/login {email?} → {loginId, url, startedAt, expiresAt} — starts a headless claude auth login --claudeai under the account's env and answers the OAuth sign-in URL. One login per account; killed after 10 min (SIDECAR_LOGIN_TTL_S).
• POST /accounts/{id}/login/code {code} → the fresh auth status — pipes the code#state the sign-in page ends on into the waiting CLI. 400 bad_code (malformed, or a #state from another attempt) keeps the login pending; 502 login_failed ends it.
• DELETE /accounts/{id}/login → {cancelled}.
• POST /accounts/{id}/logout → claude auth logout + the fresh status.
• POST /spawn (Bearer auth) {prompt, sessionId?, model?, cwd?, account?} → {sessionId, pid, log} — spawns detached, returns immediately.
• POST /resume (Bearer auth) {sessionId, prompt, model?, cwd?, account?} → {sessionId, pid, log} — continues an existing conversation by running claude -p <prompt> --resume <sessionId>. Reuses the original session id, so the new turns append to the same transcript and stream into the open conversation. --resume is directory-scoped, so pass the session's original cwd.
• POST /interrupt (Bearer auth) {sessionId} → {sessionId, pid, signal, ok} — sends the run's process group a SIGINT (like Ctrl+C), so Claude aborts the turn, writes a [Request interrupted by user] marker and exits. 404 if no live process is tracked for that session.

Per-session stdout/stderr is captured under logs/<sessionId>.log; the pid is recorded in logs/<sessionId>.pid so /interrupt can find the run.

Errors are {detail: {message, kind, hint?, account?}}. kind (from claude_cli.classify): auth, rate_limit, cli_outdated, overloaded, network, unknown, and for the login routes bad_code, login_failed, login_expired, login_timeout. A run that dies on launch is read from the CLI's JSON result line ("Not logged in · Please run /login") instead of echoing that line raw.

Headless login (claude_cli.py)

With no TTY, claude auth login prints an authorize URL whose redirect is Anthropic's manual code page and blocks on stdin at Paste code here if prompted >. Signing in (any device) ends on a page showing <code>#<state>; written to the CLI's stdin it's exchanged for tokens in the account's config dir. A code without #state → Invalid code… and the CLI re-prompts; a wrong one → exit 1 Login failed: Request failed with status code 400. The sidecar checks the pasted #state against the URL's before piping it, and also accepts the whole callback URL (…?code=…&state=…). A pending login lives only in the sidecar process — restarting it drops the login.

Accounts (personal vs work)

A claude run launches on one Claude login. The default account is the CLI's own config (~/.claude); SIDECAR_ACCOUNTS=work=~/.claude-work (in the unit, written by install.sh) declares more, each exported per run as CLAUDE_CONFIG_DIR. account on /spawn, /resume and /fork picks one — resume and fork must pass the account the session started on, since its transcript lives only in that account's projects/. A non-default account whose dir has no .credentials.json answers 409 (never a fallback onto the default login), ANTHROPIC_API_KEY is stripped from every run once accounts are declared, and --remote-control is only added for the default account. The account is recorded in the pidfile and listed by /sessions.

Manage

systemctl --user status  claude-sidecar
systemctl --user restart claude-sidecar
journalctl --user -u claude-sidecar -f