Help Center / Troubleshooting

Troubleshooting

Common issues with per-session readiness, runtime config, hook enforcement, fallback behavior, and AGENTS.md — with fixes. If you need the reader map, start with Start Here.

Before you troubleshoot, confirm the terms: Glossary and Compatibility.

Error "codex not found" After Install

codex binary not on PATH

Cause: The OpenAI Codex CLI is not installed, is not on PATH, or the command resolves to Kay's compatibility alias instead of the real Codex CLI.

Fix:

  • Check which codex and codex --version.
  • Confirm codex exec --help includes --ask-for-approval.
  • If the command resolves to Kay, fix PATH so the real OpenAI Codex CLI is first.
Codex readiness
which codex codex --version codex exec --help
After installing, run /sidekick:codex-delegate. This verifies the real Codex CLI before Sidekick routes implementation work to it.

Config Kay Runtime Issues

kay exec is unavailable

Cause: The Kay runtime is not installed, not on PATH, or the installed runtime predates the kay binary name.

Fix:

  • Run kay --version to verify the primary binary is available.
  • Run kay exec --help to verify non-interactive execution is available.
  • If only an old alias is available, reinstall Sidekick or install the Kay runtime path again before starting delegation.
kay exec --help

Kay provider login missing

Cause: Kay's OpenCode Go provider route is unavailable because the Kay runtime has no provider credentials.

Fix: Use Kay's native login flow:

kay login --provider opencode-go --with-api-key

Error Health Check Failures

✗ Codex CLI readiness failed

Cause: Missing binary, Kay alias masquerading as Codex, unauthenticated CLI, unsupported codex exec options, no network access, or provider-side service issue.

Fix:

  • Run which codex, codex --version, and codex exec --help.
  • Confirm codex --version does not identify Kay.
  • Confirm codex exec --help includes --ask-for-approval.
  • Log in to the OpenAI Codex CLI if authentication is missing.

✗ Kay readiness failed

Fix: Verify kay --version, kay exec --help, and provider login. If provider routing is wrong, start Kay with /sidekick:kay-delegate xiaomi, /sidekick:kay-delegate ocg, or set SIDEKICK_KAY_PROVIDER.

Config Provider Routing

Kay provider selector is wrong

Fix: Use the explicit activation form for the session:

/sidekick:kay-delegate xiaomi /sidekick:kay-delegate ocg

Codex model is not what you expected

Cause: Codex sidekick mode intentionally pins gpt-5.4-mini with extra-high reasoning.

Fix: Use Kay mode if you need Kay provider routing. Use Codex mode when you specifically want the local OpenAI Codex CLI sidekick.

Behavior Hook Enforcement Issues

Direct edits are denied after Kay or Codex mode starts

Cause: This is expected. The matching PreToolUse hook is active while the sidekick session marker exists. The shared active-sidekick selector suppresses the opposite sidekick for that host session.

Fix: Delegate through the active sidekick. Use kay exec in Kay mode or codex exec in Codex mode; Sidekick manages the runtime flags.

Audit index is not writable

Cause: The project-local .kay/conversations.idx or .codex/conversations.idx path is missing, unwritable, or symlinked outside the project.

Fix: Remove any symlinked audit path, fix permissions, then reactivate the sidekick.

Behavior Runtime Stuck

Sidekick keeps repeating the same action without progress

Cause: The active runtime may be trying the same fix repeatedly or working from an ambiguous prompt.

Symptoms: Output shows the same file being edited multiple times with no net change, or the same error appearing after each attempt.

Fix:

  • Tell the host exactly what is repeating.
  • The host should classify the issue, narrow the correction prompt, and relaunch the active sidekick.
  • If the runtime or provider is externally blocked, the host should report the blocker instead of treating partial output as complete.

Behavior Verification Fails

Sidekick claimed success but verification failed

Cause: A sidekick success message is not proof. The host found one or more failure classes during verification.

Fix: The host should relaunch the active sidekick with the original task, failure code, evidence, relevant files/tests, and exact success criteria. Common failure codes include MISSED_REQUIREMENT, INTEGRATION_ERROR, REGRESSION, WRONG_LOGIC, SYNTAX_ERROR, and WRONG_FILE.

Verification command fails because of an external dependency

Fix: Classify as EXECUTION_ERROR_EXTERNAL or API_FAILURE, retry after the dependency is available, or report the blocker with evidence. Do not mark the task complete from partial output.

Behavior AGENTS.md Issues

New instructions not being added to AGENTS.md

Cause: The deduplication check found a semantically similar entry already exists.

This is correct behavior — the dedup prevents duplicate entries. If you believe the new instruction is genuinely different, ask the host to add it with explicit phrasing that distinguishes it from existing entries.

AGENTS.md has wrong content

Fix: Edit ./AGENTS.md directly. Keep it focused on current Sidekick: Kay and Codex only, canonical workflows under skills/, generated host bundles under agents/, and host-owned verification.

Recovery Session Recovery

Wrong sidekick appears active

Fix: Stop the current sidekick, then activate the one you want:

/sidekick:kay-stop /sidekick:codex-stop /sidekick:kay-delegate /sidekick:codex-delegate

Reset Reinstall / Full Reset

To do a clean reinstall of Sidekick from the host plugin surface (preserves AGENTS.md and session logs):

/plugin install alo-labs/sidekick # This refreshes the plugin surface but does not delete AGENTS.md or site/sessions/

To reset a runtime credential or login, use the runtime's own login flow, then reactivate the sidekick for the current session.

Still stuck? Open an issue at github.com/alo-exp/sidekick/issues with the sidekick command, runtime readiness output, verification command output, and any relevant redacted logs.
Command Reference