Gabriel Vidal
30a9d98c36
POST /accounts/{id}/login drives `claude auth login --claudeai` without a
TTY (URL scraped, code#state piped to stdin, #state checked first);
/login/code, DELETE /login and /logout complete the flow. Launch failures
are read from the CLI's JSON result line and classified (auth, rate_limit,
cli_outdated, …) into {message, kind, hint, account}.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
128 lines
6.1 KiB
Markdown
128 lines
6.1 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
systemctl --user status claude-sidecar
|
|
systemctl --user restart claude-sidecar
|
|
journalctl --user -u claude-sidecar -f
|
|
```
|