Troubleshooting
If a review didn't appear or behaved oddly, start here.
Review didn't appear on my PR
In order of likelihood:
1. The App isn't installed on that repo. Open the GitHub App settings and check the repository list. New repos added to an org aren't auto-included.
2. Your public-repo tier is capped for the month. Public repos get 10 reviews per repo per calendar month. Private repos have no cap. Upgrade or wait for the first of the month.
3. The PR has no reviewable files. Lockfiles, binary files, deleted-only files, and anything matching ignore_paths in .commentsoncode.yml is skipped.
4. The diff is over 50 files. We review the first 50 and skip the rest — with a note on the PR. Split the PR.
5. Claude had a hiccup. We retry once on any Claude failure, then post a terse error comment. Push a new commit to retry — each new head SHA is a fresh review.
CLI: authentication failed
401 Unauthorized on codecomments review means one of:
Token was revoked. Check the token's status on dashboard → settings → CLI tokens. Revoked tokens never come back; generate a new one and re-run codecomments auth.
Token pasted with a typo or trailing whitespace. Run codecomments whoami — it prints a fingerprint. If the fingerprint is missing or unexpected, re-run codecomments auth <token>.
CLI: rate limit exceeded
The review endpoint allows 20 reviews per hour per user. A 429 response tells you the window reset time in its body.
If you hit this during CI: batch by commit, not by push. Each PR's GitHub-App review doesn't count against the CLI quota.
Too many findings
P4 SUGGESTION findings never post to PR threads — they're dashboard-only. If you're still seeing noise, the likely cause is code patterns we repeatedly flag in your codebase. Options:
Add an ignore path. If the noise is concentrated in one directory (generated code, migrations), add it to ignore_paths.
Add a custom check that permits the pattern. E.g. "This codebase uses synchronous logging in webhook handlers by design — do not flag it." Custom checks are additive to the standard 5 and steer the model toward your conventions.
Review feels wrong
We'd rather know. support@codecomments.ai with the PR URL (or the CLI invocation and diff snippet) is the fastest path to a fix.
If a finding is factually wrong (claims a file is "missing" when it exists, or names a library version as "not released" when your manifest pins it), include that detail — those are the easiest cases for us to patch in the prompt.