Skip to content

Agent troubleshooting

Start by proving the provider CLI works outside AgentDock, then compare that with what AgentDock itself resolves and reports.

Most agent-specific problems fall into one of a few buckets. Work through them in order before assuming something is broken in AgentDock itself.

1. Confirm the CLI works outside AgentDock

Run the provider's own version command directly in a terminal: claude --version, codex --version, or agy --version. If that fails, the problem is with the CLI installation or authentication, not AgentDock — see Install provider CLIs and Authentication.

2. Compare that with AgentDock's own resolution

Open Settings → Agents and use the Test action for the agent in question. It reports the exact path AgentDock resolved, the executable type, and the version it found — see CLI detection and diagnostics. A CLI that works in your terminal but fails this test usually means AgentDock is launching a different executable or a different environment than your shell does.

3. Check for provider-specific failure modes

  • Claude Code — permission or tool-call failures usually show up as an interaction card; see Permissions.
  • Codex — on Windows, a bare codex on PATH can resolve to an npm .cmd shim that Codex's SDK can't spawn directly; this is exactly why Codex uses a multi-tier resolver instead of a plain PATH search — see OpenAI Codex.
  • Antigravity — because permission and authentication prompts are detected by pattern-matching terminal output rather than a structured API, an unrecognized prompt string can stall a task instead of being classified correctly. The raw terminal drawer shows the literal text AgentDock is trying to match.

4. Set a custom executable path only if needed

If detection genuinely can't find a working install, override it in Settings → Agents with a specific path rather than fighting PATH resolution — see Agent configuration.

Related