The sidecar is a Bun process that bridges Helmor's Rust backend with coding agent providers. It translates backend requests into provider-specific API calls and streams agent events back.
Communication protocol#
The sidecar uses JSON Lines over stdin/stdout — one JSON object per line in each direction.
Requests (backend → sidecar):
{"id": "req-1", "method": "sendMessage", "params": {...}}
Events (sidecar → backend):
{"id": "req-1", "type": "message", ...}
Events are routed to their matching request via the id field. A dedicated reader thread continuously reads sidecar stdout and dispatches events to per-request channels.
Supported methods#
| Method | Purpose |
|---|---|
sendMessage | Start or continue an agent session |
generateTitle | Auto-title a session based on content |
listModels | Query available models from a provider |
stopSession | Cancel an active stream |
steerSession | Mid-stream guidance to the agent |
updateConfig | Change runtime config (e.g., model) |
permissionResponse | Approve/deny a tool permission request |
userInputResponse | Answer an agent's clarifying question |
shutdown | Graceful sidecar exit |
Agent providers#
The sidecar integrates with:
- Claude Code (Anthropic) — via the Claude Agent SDK.
- Codex (OpenAI) — via the Codex SDK.
- Cursor — via the Cursor SDK.
Each provider manages its own auth. The sidecar just forwards credentials from the environment or config.
Lifecycle#
- Startup — Rust backend spawns the sidecar on first request. In dev, it runs the TypeScript source directly; in production, a bundled binary. The backend waits for a
{"type": "ready"}event before sending requests. - Health — heartbeats every 15 seconds during active streams. The backend declares the sidecar dead after 45 seconds of silence.
- Shutdown — three-step ladder: cooperative
shutdownRPC → SIGTERM (5s grace) → SIGKILL.
Related#
- Backend Overview — the supervisor that manages this process.
- Sidecar and CLI Issues — troubleshoot startup failures.