04 - Sidecar and CLI Issues#
The sidecar is the background process Helmor uses to communicate with coding agent providers. If it cannot start or reach a provider, sessions fail before the agent produces useful output.
Symptoms#
- Sessions immediately fail or hang without any agent response.
- Error messages mentioning "sidecar", "spawn", or "ENOENT" appear in logs.
- One or all agent providers are unreachable.
Quick fixes#
- Restart Helmor — kills the sidecar and spawns a fresh instance on next session.
- Verify agent CLI — run the agent outside Helmor to confirm it works:
claude --version # Claude Code codex --version # Codex - Check PATH — Helmor inherits the system
PATH. If the agent binary is in a non-standard location, add it to your shell profile and restart Helmor. - Refresh credentials — expired API keys or revoked tokens cause immediate provider rejection. Re-authenticate with the provider.
Development environment#
If you are running Helmor from source, ensure the sidecar is prepared before launching:
bun install
bun run dev:prepare # builds the sidecar binary
bun run dev # starts Helmor with hot reload
Skipping dev:prepare after pulling new changes is a common cause of sidecar mismatch errors.
Log inspection#
Enable debug-level sidecar logging:
HELMOR_LOG=helmor::sidecar=debug bun run dev
Look for:
- Spawn failures (binary not found or permission denied).
- Connection timeouts (network or provider outage).
- JSON parse errors (protocol mismatch between Helmor and the agent CLI version).
Recovery matrix#
| Scenario | Action |
|---|---|
| One provider fails | Reconnect that provider's credentials. |
| All providers fail | Focus on sidecar startup — check binary existence and env vars. |
| Dev mode only | Run bun run dev:prepare and retry. |
Related#
- Debugging Guide — full layer-by-layer troubleshooting.
- Agent — supported agents and auth requirements.