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.