Help

Troubleshooting

Fixes for common problems — installing, signing in, updates, usage limits, macOS and Windows warnings, Linux AppImages, MCP servers, the browser and the terminal.

#Start with doctor

loopcode doctor

doctor checks the installation, your sign-in, the connection to LoopCode, and the tools the agent uses — git, the GitHub CLI, a browser — and says what to fix.

#Installing

loopcode: command not found after installing. Open a new terminal, so it reads the updated PATH. The command is in ~/.local/bin (or LOOPCODE_BIN_DIR); on Windows, in a folder on your user PATH. If you installed with LOOPCODE_NO_MODIFY_PATH=1, add that folder to your PATH yourself.

Node.js is old or missing. Nothing to do: the installer brings its own Node.js for LoopCode when yours is older than 22.18.

macOS says "Apple could not verify LoopCode". LoopCode is not notarised yet. Install it from the terminal instead, which checks the app itself and opens it without the warning:

curl -fsSL https://loopcode.heksync.in/mac.sh | sh

Or, for a copy you downloaded: open System Settings → Privacy & Security, and choose Open Anyway for LoopCode.

Windows SmartScreen or Smart App Control blocks it. Install with irm https://loopcode.heksync.in/win.ps1 | iex, which checks the installer and avoids the SmartScreen prompt. If Smart App Control still blocks it, write to team@heksync.in.

The Linux AppImage does not start. Make it executable (chmod +x LoopCode-*.AppImage). On Ubuntu 22.04 and later, install FUSE 2: sudo apt install libfuse2.

#Signing in

The browser did not open. Copy the address loopcode login prints and open it on any device — the approval works from a phone or another computer, which also makes it work over SSH.

The code does not match. Do not approve. Close the page and run loopcode login again.

"Not signed in" in CI. CI cannot sign in with a browser. Create a token with loopcode token create and set it as LOOPCODE_TOKEN. See Headless mode and CI.

Switching accounts. loopcode logout, then loopcode login.

#Updates

The CLI did not update. Run loopcode update. If it says the copy cannot update itself, it was not installed with the installer — reinstall with it, and it will keep itself current. Check that LOOPCODE_NO_AUTOUPDATE is not set.

The desktop app keeps asking to restart. A new version is downloaded and waiting. Restart to update; your conversations carry over. "Later" puts the reminder away for an hour.

#Usage limits

"Usage limit reached". A usage window is used up. The agent pauses until it resets — nothing is lost, and the conversation continues afterwards. loopcode usage shows when each window resets; loopcode upgrade raises the limits. See Plans and usage.

Model errors that go away by themselves. Brief model-service errors are retried automatically, and a stopped turn resumes. If one keeps failing, try another model with /model.

#The agent

It keeps asking for permission. Switch to Auto-review (shift tab), or answer Always allow for commands you trust; or add permission rules.

It does something it should not. Press esc to stop the turn, /rewind to undo its file changes, and tell it what to do differently. Add a deny rule or a line in LOOPCODE.md so it does not happen again.

It forgot something from earlier. Long conversations are compacted. Put lasting facts in memory (# …) or LOOPCODE.md, and start a new conversation per task.

It cannot finish because a check fails. That is proof of done working. If a check genuinely does not apply to the project, drop it in settings ("proof": { "lint": false }).

#MCP servers

A server shows an error. Its own error output is in ~/.loopcode/logs/mcp/. Check the command runs on its own in your terminal, and its environment variables are set.

A server needs sign-in. loopcode mcp login <name>, or Sign in in /mcp.

#Browser

No browser found (CLI). Install Chrome or Chromium, or point LOOPCODE_BROWSER_PATH at one. In CI or on a server without a display, set LOOPCODE_BROWSER=headless.

#The terminal

shift enter sends instead of adding a line. Use ctrl j. If other keys misbehave, set LOOPCODE_TUI_DISABLE_KEYBOARD_ENHANCEMENT=1.

Searching is slow in a huge repository. LoopCode searches with ripgrep when it can find it. Install it (brew install ripgrep, apt install ripgrep, winget install BurntSushi.ripgrep.MSVC) or point LOOPCODE_RG_PATH at it.

#Still stuck?

loopcode feedback "what happened, and what you expected"

That opens a message to team@heksync.in in your mail app (in the desktop app: Help → Send Feedback…). Include your operating system and loopcode --version. Never send access tokens, API keys or project secrets.