Common problems

Each problem below starts with what Revue says, word for word. Where the problem has an error code, the fix is under that code on Error codes, and an error’s details name its code (“Error GH-006”). If your problem isn’t here, see Get help.

Setup and sign-in

Git is missing

Setup’s Git row says:

“Install Apple’s tools: {…}”

Revue needs git, which comes with Apple’s command line developer tools. Choose Copy command, paste it into Terminal (it’s xcode-select --install), and follow the installer. Then choose Check again.

The GitHub CLI has no sign-in to share

“The GitHub CLI has no sign-in to share. Run {…}.”

Revue can use the GitHub CLI’s sign-in, and the CLI has none. See GH-006.

GitHub isn’t connected

“Connect GitHub to see your pull requests.”

Revue has no GitHub account to read with. See GH-002.

GitHub’s rate limit was reached

“GitHub’s rate limit was reached. Check again in a few minutes.”

See GH-001.

Revue can’t reach GitHub

“Couldn’t check your GitHub connection. Local review still works.”

See NET-001.

The sign-in code expired or was declined

“This code expired. Generate a new one to continue.”

“Authorization was declined on GitHub. Try again whenever you are ready.”

See GH-002.

Revue couldn’t install the command line tool

“Revue couldn’t write to {…}. Run this in Terminal instead:”

The folder for the revue command, /usr/local/bin, belongs to an administrator on a new Mac. Choose Copy command, paste it into Terminal and enter your password when sudo asks. Then choose Check again.

The revue command opens another copy of Revue

“The revue command needs updating”

“It still opens {…}.”

The revue command was installed by a copy of Revue that has moved or gone. Choose Point it here, and Revue shows what it will write before it changes anything. Setup’s Command line tool row offers the same.

Updates

Revue is running from the disk image

“Move Revue to Applications and open it from there to get updates.”

“macOS is running Revue from a temporary location. Move Revue to Applications, then open it again.”

See APP-004.

An update can’t be installed

“Revue couldn’t replace itself in {…}. Move it to your own Applications folder, or ask an administrator.”

See APP-004.

Revue can’t reach the update server

“Revue couldn’t reach the update server.”

See APP-004.

An update failed its signature check

“The update list failed its signature check, so Revue ignored it. Nothing was installed.”

“An update was downloaded but failed its signature check, so it wasn’t installed.”

Nothing on your Mac changed. See APP-004.

Claude Code and Codex

Claude Code not found

“Claude Code not found. Install it”

Codex shows the same message with its own name. See AI-001.

The plugin is turned off

“Claude Code has the plugin turned off, so sessions don’t receive the comments you send.”

Choose Turn on in Settings › AI review or in Setup. See Claude Code plugin.

Revue is missing

At the start of a Claude Code session, Claude says the Revue plugin is installed but Revue itself is missing or too old. The plugin can’t find a revue it can run. Install or update Revue, open it from Applications, then run revue agents install so the plugin records where Revue is. If you’ve stopped using Revue, remove the plugin with claude plugin uninstall revue@revue.

No agent session shows

The plugin acts only in checkouts Revue knows. Open the checkout in Revue first, then start Claude Code in it, or start a new session if one was already running.

The session says Not listening

“Not listening”

A session waits up to 30 minutes for your comments after each turn, then stops listening. Nothing is lost: comments you send arrive with your next prompt.

The session says Idle

“Idle (no recent activity)”

Revue has heard nothing from the session for over 10 minutes. Claude Code says nothing when you press Esc to interrupt a turn, and a single long tool call reads this way too. The session hasn’t ended. Your next prompt, the next tool call or the end of the turn shows its state again.

No checkpoints are recorded

Checkpoints are recorded on the checked-out branch, so a detached HEAD records none. Check out a branch.

Codex can’t run revue commands

“Revue’s data folder is read-only here.”

Codex’s workspace-write sandbox stops it writing to ~/.revue. Add the folder’s full path to ~/.codex/config.toml, then start Codex again:

[sandbox_workspace_write]
writable_roots = ["/Users/you/.revue"]

See Use Revue with Codex.

AI review

An AI turn timed out or ran out of credit

“Your Anthropic account is out of credit. Add credit, then try again.”

See AI-002 and AI-003.

A fix touches files that can run code

“These files can run code on checkout, build or when an editor opens them.”

See AI-016.

Live updates

Keychain access wasn’t allowed

“Try again, then choose Always Allow when macOS asks.”

macOS asked before Revue read your browser’s key in the Keychain, and it was refused. See NET-002.

Live updates need GitHub signed in

“Live updates need GitHub signed in through {…}. {…} isn’t signed in. Sign in to GitHub there, or choose another profile. Revue retries on its own.”

Live updates read your GitHub sign-in from a browser profile, and that profile isn’t signed in. Sign in to github.com in it, or pick another profile in Settings › Live updates. Pull requests still update through pull request sync.

Chrome isn’t installed

“Live updates need GitHub signed in through {…}, and {…} isn’t installed on this Mac. Install it and sign in to GitHub there, then {…}.”

Revue reads the sign-in from Chrome unless your default browser is Brave or Firefox. Install the browser, sign in to GitHub there, or choose another browser in Settings › Live updates.

Posting

A comment may have posted

“Couldn’t confirm what GitHub saved. Refresh to check before trying again.”

The card says May have posted. See GH-011.

Development builds

The command line can’t see a development build’s data

A development build started with REVUE_NATIVE_DATA_DIR=<dir> keeps its data in that folder, while the agent commands, such as revue comments, read ~/.revue. Run them with REVUE_DATA_DIR=<dir>/backend. See Environment variables.