01 - Agent Not Responding#
When an agent session starts but produces no output — or hangs indefinitely — the problem usually lives in the sidecar, the agent CLI, or the provider credentials.
Symptoms#
- Session shows "streaming" but no messages appear.
- The session timeline stays empty after sending a prompt.
- A timeout error appears after ~45 seconds.
Step-by-step diagnosis#
1. Verify the agent CLI works independently#
Run the agent outside Helmor:
claude --version # Claude Code
codex --version # Codex
If these fail, the agent isn't installed or isn't on your PATH. Install it and restart Helmor.
2. Check provider credentials#
Each agent authenticates with its own provider:
| Agent | Credential check |
|---|---|
| Claude Code | ANTHROPIC_API_KEY set, or Claude Pro subscription active |
| Codex | OPENAI_API_KEY set and valid |
Expired or revoked keys cause silent failures — the sidecar connects but gets rejected.
3. Restart Helmor#
A fresh launch kills the sidecar and spawns a new one on the next session. This clears stale process state.
4. Check sidecar logs#
Enable debug logging:
HELMOR_LOG=helmor::sidecar=debug bun run dev
Look for:
- Spawn failures — binary not found, permission denied.
- Connection timeouts — provider unreachable (network issue or outage).
- JSON parse errors — protocol mismatch (update the agent CLI).
5. Rebuild the sidecar (dev mode)#
If you're running from source:
bun run dev:prepare
bun run dev
Skipping dev:prepare after pulling changes is a common cause of sidecar mismatch.
Still stuck?#
- Check if the provider has a status page (status.anthropic.com, status.openai.com).
- File an issue at github.com/dohooo/helmor/issues with logs and the exact error.
Related#
- Sidecar and CLI Issues — broader sidecar troubleshooting.
- Logs and Diagnostics — where to find log files.