CLACOROO
EN IT
Download

Troubleshooting & FAQ

This is the catch-all page. If something isn’t working as expected, look for the symptom here first — and then jump to the relevant feature page for context.

Installation

”Windows protected your PC” on the installer

Click More info, then Run anyway. CLACOROO is signed with an ad-hoc certificate, not a paid Microsoft / Apple Developer ID. The first-launch warning is the only friction; subsequent launches are silent.

macOS: “CLACOROO cannot be opened because the developer cannot be verified”

Quit the dialog, right-click CLACOROO in Applications, choose Open. Click Open again in the next dialog. From now on, it opens normally.

If you don’t see “Open” on right-click, go to System Settings → Privacy & Security; near the bottom you’ll find a section listing the blocked app with an Open Anyway button.

Linux: AppImage doesn’t run

Make it executable: chmod +x CLACOROO-x.y.z-arm64.AppImage. If your file manager refuses to open it on double-click, run it from a terminal: ./CLACOROO-x.y.z-arm64.AppImage. Or install AppImageLauncher for desktop integration.

If you see a libfuse error, install FUSE 2 (sudo apt install libfuse2 on Ubuntu).

First launch

”claude not found” toast

CLACOROO can’t find the claude binary on your shell PATH.

  • macOS / Linux: open a terminal, run which claude. If it returns nothing, Claude Code isn’t installed (yet). Install it from claude.com/claude-code.
  • Windows: open PowerShell, run where.exe claude. If it returns nothing, Claude Code is missing or not in your PATH. CLACOROO looks for claude.exe specifically in %USERPROFILE%\.local\bin; make sure that folder exists and contains claude.exe, then restart CLACOROO.

After fixing this, click Refresh in CLACOROO’s topbar — the toast should disappear and the Dashboard should populate.

The Dashboard is empty

Either:

  • Claude Code is freshly installed (no sessions, no plugins) — that’s expected; once you start using it, numbers will appear
  • CLACOROO doesn’t have read access to ~/.claude/ (or %APPDATA%\Claude\ on Windows) — check folder permissions

The onboarding tour didn’t appear

It runs once on first launch. Replay it from Settings → Onboarding or Cmd/Ctrl + K → “Restart tour”.

Accounts & quotas

”Login to claude.ai” does nothing

CLACOROO opens the built-in terminal with claude login preloaded — if you don’t see the terminal drawer open, it’s hidden. Press the backtick key (Cmd / Ctrl + backtick, the key above Tab) to bring it up.

If the command runs but the OAuth flow stalls, the callback URL might not reach your machine. Use the device-code variant: in the terminal, type claude login --headless and follow the printed URL.

Quotas show — even though I’m logged in

Claude Code hasn’t received a fresh quota response yet. Send a message in a Claude Code session, then click Refresh in the account panel.

API key works in test but Claude Code doesn’t use it

Verify what Claude Code is configured to use: in the built-in terminal, run claude config get apiKeyHelper. The path should point to the CLACOROO helper file. If it points elsewhere, run Test connection then Save key again to re-register.

Notifications don’t appear

See Quota notifications · Edge cases. The most common cause is “Do Not Disturb” or focus mode. Test with the Test notification button; if the in-app toast appears but no system notification follows, it’s an OS-level permission issue.

Plugins, marketplaces, skills, agents

”Plugin update failed” toast

Open the built-in terminal and run the same command that CLACOROO tried (visible in the failure toast on hover). The CLI prints the full error: usually a marketplace reachability issue or a version conflict.

A plugin keeps reappearing after Remove

It’s pinned by settings.json or by a parent CLAUDE.md. Open Claude Config to inspect, or read ~/.claude/settings.json directly.

”Marketplace already exists” when adding

You’ve already added this source under a different alias. Open the existing card instead of trying to add a duplicate.

A skill or agent shows health: error

Its front matter or one of its Markdown blocks is malformed. Open the Skills or Agents section, click the item title; the preview modal shows the parse error line.

MCP servers

A server stays at “Connecting…”

The transport might be wrong, or the endpoint is unreachable. Click the status badge on the card to see Claude Code’s last raw error. Often: wrong URL, missing auth header, or you picked http when the server only speaks stdio.

”Needs Auth” doesn’t go away after authenticating

Click Clear auth cache on the card, then Refresh. If the status stays stuck:

  • For OAuth servers, log out and log back in to claude.ai
  • For token-based servers, edit the registration (in claude_desktop_config.json) to ensure the right token is in the right header

Can’t remove a server

You can only remove user-added servers. Built-in or plugin-provided servers are managed elsewhere — disable the owning plugin instead.

Hooks

A hook keeps saying “missing dep”

Claude Code resolves tools via PATH. If you installed the tool but the badge stays yellow:

  • Restart CLACOROO so the new PATH is picked up
  • Verify the tool name matches exactly (jq vs JQ is significant on case-sensitive filesystems)
  • Open the built-in terminal and run which <tool> to verify

A hook fires multiple times

Two plugins ship the same matcher on the same event. Filter the Hooks section by event to see duplicates side by side; disable one of the contributing plugins if you don’t want both.

Hooks listed but nothing seems to run

Check the dependency badge first (missing dep = silent no-op). Then verify the plugin that owns the hook is enabled in the Plugin manager — disabled plugins still list their hooks, but they don’t fire.

Terminal

Tabs say “exited” right away

Your default shell isn’t available, or your $SHELL env var points at a non-existent binary. Open a system terminal, check echo $SHELL, and fix it (/bin/zsh, /bin/bash, etc.).

Input doesn’t reach the shell

Click inside the terminal area to give it focus. If that’s not it, the shell may have exited — open a new tab.

Paste is truncated

Some shells limit paste size or interpret newlines incorrectly. Use bracketed paste mode (most modern shells: printf '\e[?2004h' to enable), or save the snippet to a file and cat from there.

Settings & config

Changing a setting doesn’t seem to take effect

Most settings apply at the start of the next Claude Code session. Start a fresh session in Claude Code and try again.

settings.json has a parse error

CLACOROO will show the error in the Claude Config section. Open the file in your editor of choice (the path is shown in the description for each row), fix the JSON, save. CLACOROO picks it up on the next refresh.

Updates

CLACOROO offers a new version, but I don’t want to update yet

Dismiss the banner. The next time you launch the app, it’ll show up again — there’s no “skip this version” toggle, by design.

After update, my settings are gone

CLACOROO updates preserve all state (database, settings, snapshots). If everything looks reset, check:

  • You opened the right binary (especially on Linux where AppImages don’t replace the previous one automatically)
  • Your CLACOROO data folder still exists (~/Library/Application Support/CLACOROO/ on macOS, %APPDATA%\CLACOROO\ on Windows, ~/.config/clacoroo/ on Linux)

How do I roll back to a previous version?

Download the older installer from the GitHub releases page and run it. CLACOROO’s state is backward-compatible across recent versions.

Where to ask for help

  • GitHub issues: github.com/Maxymize/clacoroo/issues — best place for bug reports and feature requests
  • CLAUDE.md (in the repo): contributors can find architecture and conventions documented there

When reporting an issue, include:

  • Your OS and CLACOROO version (visible at the bottom of the sidebar)
  • The exact steps you took
  • The error message (full text or screenshot)
  • Whether the same operation works from the CLI (claude ... in the built-in terminal)

Sending feedback from the app

Since v1.1.23, there’s a Feedback button in the sidebar footer, near the version number. Clicking it opens the feedback form on the website in your browser, already set to the app’s language. Pick a type — Bug, Feature request, Question, or Other — and describe what you ran into. Technical reports become anonymous public issues on GitHub: your name and email are used privately only so we can reply, and never appear in the public issue.