Common situations, what they look like, and what to do. Every message below is real shipmoor review output.
”requires entitlement ‘cli_pro’” (the feature is locked)
$ shipmoor review .
shipmoor pro: requires entitlement 'cli_pro'. IC features are available after sign-in; run `shipmoor login`.Under --json you get the shipmoor.paid_feature_error.v1 contract instead. Both exit with code 2.
Fix: shipmoor review is a Pro feature. Sign in:
shipmoor login
shipmoor capabilities --json # confirm .capabilities.cli_pro.enabled == trueThe gate is checked first. On a locked license, Shipmoor never imports the review engine or spawns your agent.
”—agent is required to run a review”
$ shipmoor review .
shipmoor: --agent is required to run a review (or use --preview); try --agent claude (the built-in preset that drives your `claude` CLI), or set the review.agent config key.Fix: a review needs a reviewer. The easiest is --agent claude (the built-in preset that drives your local claude CLI). You can also set review.agent in .shipmoor.yaml, pass a custom wire-contract command, or run --preview (which plans the run without an agent). Exit code 2.
”agent command ’…’ not found” (most commonly --agent self)
$ shipmoor review . --agent self
shipmoor: agent command 'self' not found. Pass --agent with a reviewing agent: use the built-in preset --agent claude (drives your `claude` CLI), or a command that speaks the wire contract (see examples/agents/example-agent.py).This is exit 2 (a usage error: the agent never ran).
The most common cause is passing --agent self literally. self is a Skills-context placeholder (it means “the agent already running this skill is the reviewer”). The bare CLI has no self keyword: it shlex-splits --agent and tries to launch a program called self, which does not exist.
Fix: outside a Shipmoor Skill, use the built-in claude preset (it drives your local claude CLI for you):
shipmoor review . --agent claudeThe same exit-2 error appears for any --agent whose program cannot be launched: a typo, a binary not on PATH, or a script that is not chmod +x. To bring your own agent, remember that a raw claude -p does not speak the wire protocol. Copy the runnable example-agent.py reference (described in AI coding agents), point --agent at it, or just use the claude preset above.
The review “failed” (exit 3: the agent ran but the run failed)
$ shipmoor review . --agent "my-agent"
Advisory code review — failed
review failed: all 1 file review(s) failed — check your LLM configuration and API keyExit 3 is an operational failure (distinct from the exit-2 “not found” above): the agent launched but every file’s review failed. Common causes: the agent returned malformed JSON or an empty choices array, exited non-zero, wrote non-UTF-8 to stdout, or exceeded --timeout on every file. Check the agent against the wire contract. The reference example-agent.py is a known-good implementation to compare against.
Large diffs and slow reviews
A review runs per file with a worker pool. If runs are slow or time out:
- Raise the per-file timeout:
--timeout 300(default120seconds). - Tune parallelism:
--concurrency(default8). Raise it to review more files at once, lower it to ease load on your agent’s provider. - Narrow the change: review a tighter selection (
--staged,--commit, or a smaller--from/--torange) instead of the whole working tree. - Exclude generated code from whole-file (
--scan) mode viareview.excludein.shipmoor.yaml, for example"**/generated/**". - In the IDE, the review timeout is
shipmoor.review.timeoutMs(default180000ms).
Non-ASCII and non-UTF-8 file paths
Files with accented or non-UTF-8 names (for example café.py, or a filename with raw non-UTF-8 bytes) are surfaced, not silently dropped. Shipmoor reads git paths with quoting disabled and decodes them losslessly, then renders any non-representable bytes as escaped, JSON-safe text in the findings. If you noticed such a file being skipped in an older build, it now appears in the review and in the findings[] output.
”Why didn’t the review fail my build or block the merge?”
By design. shipmoor review is advisory: it never returns the “threshold breached” exit code (1) and is structurally excluded from the shipmoor scan --fail-on gate. A review with findings, even ones the model calls critical, still exits 0.
If you want a merge to be blocked on findings, that is the job of the deterministic gate:
shipmoor scan . --changed --fail-on high # THIS gates (non-zero exit on breach)Run the two together: the scan gates, the review advises. See CLI reference: combining with the gate and CI integration.
Advisory versus gate, at a glance
| You want… | Use |
|---|---|
| A second opinion that never blocks | shipmoor review (advisory) |
| A merge blocker on deterministic findings | shipmoor scan --fail-on <sev> (the gate) |
| Both | The gate decides pass or fail; the review comments alongside |
In the IDE: review findings are not in my problem count
That is intended. Advisory review findings render as Information-level diagnostics in a separate shipmoor-review collection with the source Shipmoor (advisory), and the status bar counts only structural (Shipmoor-sourced) findings. Your problem count stays an honest tally of structural issues; advisory comments live alongside without inflating it. See IDE.
FAQ
Does Shipmoor send my code to a model or a server?
No. Shipmoor hosts no model and uploads no source. Your --agent command runs locally as a subprocess. The only network traffic is whatever your agent does to reach its provider. A local or offline agent makes no network calls at all.
Which languages does the reviewer support? The reviewer works over your diff or files via your agent. The structural scan and IDE surface support Python, TypeScript, JavaScript, and Go.
Can I run a review without an agent at all?
Only --preview (it plans the run without invoking an agent). An actual review needs --agent.
Is there a --changed or --fail-on flag on review?
No. The working tree is the default (no --changed needed), and there is no --fail-on because a review never gates. Those flags belong to shipmoor scan.
What is the difference between the shipmoor-review and shipmoor-code-review Skills?
shipmoor-review (Community) wraps the deterministic gate (shipmoor scan). shipmoor-code-review (Pro) wraps the advisory AI reviewer (shipmoor review). See AI coding agents.