Troubleshooting

loci CLI not found

1. Check it's on PATH: command -v loci and loci --version.

2. If missing, the background install may still be running or may have failed. Run /loci:setup to reinstall and verify — it's safe to re-run.

3. Confirm uv is installed (command -v uv) — the plugin needs it to install the CLI.

4. If the install itself failed, check ~/.loci/state/loci-cli-install.log for the cause (commonly: uv can't reach PyPI, or an old uv version).

A skill reports auth_required

Every analysis skill needs a signed-in session (see Authenticating).

1. Run ! loci login, then retry.

2. Confirm with ! loci auth status that it shows signed_in.

A skill reports quota_exceeded

You're signed in, but you've hit your plan's daily limit. The error message includes the reset time and an upgrade link — this is not a bug, and retrying won't help until the window resets.

Auto-skills didn't fire

• loci-preflight only runs in /plan mode — confirm you're describing new logic, not just asking a question.

• loci-post-edit only runs after edits to C/C++/Rust source files (.c, .cc, .cpp, .cxx, .h, .hpp, .hxx, .rs).

• Both compile the source themselves — they need a supported LOCI target and a working cross-compiler for it on PATH, plus a valid session context from startup. If the compiler is missing, install it (or point LOCI at it) and re-run.

On-demand skills didn't respond

• Type /help to confirm LOCI is loaded and see the full skill list plus your environment status.

• Restart Claude Code from inside your project directory if the build environment wasn't detected at session start.

• Check that a cross-compiler is installed and on PATH for your target — see the Installing prerequisites table.

Environment health check

! loci doctor

Runs 10 checks (Python version, analysis-stack imports, c++filt, credential store, sign-in, state directory) and reports data.healthy: true/false plus per-check detail. Works signed out.

Nothing seems to work

Run /bug-report and describe what you expected vs. what happened. It generates a full diagnostic report — environment snapshot, a 10-point checklist, and root-cause reasoning — as a timestamped .md file you can share with support or load into a new Claude Code session for further investigation. It works even when LOCI is completely broken (it avoids calling any of the analysis commands that might be the thing that's failing).