More
Troubleshooting
Common problems and how to fix them. A good first step for most of them: run dotpals status to see what's running and connected.
The downloaded app (.exe, .dmg)
- “Windows protected your PC”, or macOS won't open it. The app isn't signed yet. On Windows, click More info, then Run anyway. On a Mac, open it once, then System Settings → Privacy & Security → Open Anyway. You're asked only the first time. If Windows Smart App Control blocks it outright, use
npx dotpals@latest setupinstead. - Keep it in Applications (macOS). Agents' hooks run dotpals from where it is. Opened from the disk image or Downloads, it offers to move itself there.
- What did the first start set up?
~/.dotpals/setup.loghas setup's messages. Run it again any time with~/.dotpals/bin/dotpals setup, and check everything with~/.dotpals/bin/dotpals doctor. - Hooks run on the app. Cursor, Gemini CLI and Copilot CLI's hooks run
~/.dotpals/bin/dotpals-node, the app itself as Node, so they work without Node.js. If you uninstall the app, they quietly do nothing until you Disconnect them. The Claude Code plugin's hooks runnode; without Node.js the app doesn't add the plugin, and Claude Code's sessions show from its transcripts. - Updating. The app updates itself. Once a day it asks GitHub for a newer release, downloads its installer to
~/.dotpals/updates, checks it against the release'sSHA256SUMS.txt, and installs it when dotpals quits, or right away when you click the notification. Your settings and history stay. To update by hand, download the new version and install it over the old one.
The one-line installer stops
The installers (install.ps1 on Windows, install.sh on macOS and Linux, and the double-click files that run them) install Node.js if you need it, then run npx dotpals@latest setup. If one stops:
- “Windows protected your PC”, or macOS says it can't check the file. The double-click installers aren't signed yet. On Windows, click More info, then Run anyway. On a Mac, open System Settings → Privacy & Security and click Open Anyway (on macOS 14 and earlier, right-click the file and choose Open). You're asked only the first time.
- Node.js didn't install. Install Node.js 20 or newer from nodejs.org, open a new terminal and run
npx dotpals@latest setup. On Linux the installer doesn't pick a package manager for you: nodejs.org shows the commands for your system. - You said no when Windows or your Mac asked for permission. Node.js is installed for every app on the computer, which needs your permission. Run the installer again and say yes.
- “Node.js 20 or newer still isn't the one on your PATH”. An older Node from a version manager comes first. Switch it to 20 or newer (with nvm:
nvm install --lts) and run the installer again. Your agents run dotpals' hooks with thenodethat comes first, so it matters. - “dotpals setup didn't finish”. Setup's own messages, just above, say why; the rest of this page covers most of them. Still stuck? Ask, with what it printed.
The pal isn't showing my sessions
- Is dotpals running? Look for the tray icon, or run
dotpals status. If it says dotpals isn't running, start it withdotpals start. The pal says “bridge offline, retrying…” while it can't reach the bridge. - Windows: is
nodeon the PATH apps get? The Claude Code plugin's hooks runnodeby name, and an editor started from the Start menu doesn't see aPATHset only in your terminal (fnm, for example). Rundotpals doctor: it checks, and says how to add Node's folder to your userPATH. Claude Code's sessions still show up from their transcripts meanwhile. - Claude Code: restart it after installing the plugin. Claude Code loads plugins when it starts, so sessions that were already open don't send hook events. They still show up, because dotpals follows every session's transcript in
~/.claude/projects(those written in the last three hours), just a second or two behind and without permission prompts. If you've setDOTPALS_CLAUDE_LOGS=0, only the plugin's hooks count. - Codex: nothing to set up, but dotpals has to be running. It follows logs from today and yesterday, and shows a pal only for sessions active in the last 10 minutes.
- Other agents: check the dashboard's Agents page. The card should say Connected and show a recent event. Press Send a test event; if it fails, it says why. See An agent won't connect.
- Is the agent switched off? The switch on each Agents card (or
"agents"inconfig.json) makes dotpals ignore it. - Maybe it's just quiet. Small mode shows only active agents (working, waiting, or busy in the last two minutes). The session tabs list sessions active in the last 30 minutes. After 15 minutes of silence a session ends and its pal leaves, and a session you dismissed with × on its tab stays away until the agent does something new. Every session is still on the dashboard's Sessions page.
The desktop pal doesn't open (ELECTRON_RUN_AS_NODE)
If the environment variable ELECTRON_RUN_AS_NODE is set, Electron runs as plain Node: no window appears, or you see Node-style errors instead. Some programs set it for the processes they start (for example, tools running inside some Electron-based editors).
dotpals' own launchers remove it: dotpals setup, dotpals start, dotpals-float and the hooks that start the pal. So the simplest fix is to start dotpals with one of those. If you run Electron yourself, clear the variable first:
# PowerShell
Remove-Item Env:ELECTRON_RUN_AS_NODE -ErrorAction SilentlyContinue
# macOS and Linux
unset ELECTRON_RUN_AS_NODE
If it's set in your user or system environment permanently, remove it there.
npm won't install from GitHub
The normal install, npx dotpals@latest setup, comes from npm and doesn't touch git. This only matters if you install straight from GitHub: npm 12 and newer refuse that unless you allow it, so that command includes --allow-git=all:
npx --allow-git=all github:rikinshah787/dotpals setup
Older versions of npm ignore the flag, so keep it either way. If your npm settings or company policy block git installs, clone the repository and run setup from it:
git clone https://github.com/Rikinshah787/dotpals.git
cd dotpals
npm run setup
Port 5175 is in use
dotpals uses port 5175. If another program has it, the pal stays “bridge offline, retrying…”, and dotpals bridge says “The dotpals bridge is already running.” and stops.
Find out what's using the port:
# Windows (the last column is the process id; look it up in Task Manager)
netstat -ano | findstr :5175
# macOS and Linux
lsof -i :5175
- If it's another dotpals bridge (for example
dotpals bridgeleft running in a terminal), that's fine: the desktop app uses it, and takes over if it stops. - If it's something else, stop it, or move dotpals to another port. That takes a few settings, so everything agrees on the new port: see Changing the port.
Claude Code's usage limits don't show
The notch shows “Claude's limits: run dotpals statusline once” until they arrive.
- Run
dotpals statusline. Setup doesn't do this for you, because it changes your Claude Code settings. Claude Code shares its limits only with a status line command. - Run it after setup, so the status line points at the installed copy.
statusLine.commandin~/.claude/settings.jsonshould end in.dotpals/app/bridge/statusline.js. If it points somewhere temporary, rundotpals statusline --off, thendotpals statuslineagain. - Use Claude Code for a moment. The limits are saved when Claude Code refreshes its status line, and the notch checks every 20 seconds. They're kept in
~/.dotpals/claude-limits.json. - If that file never gets a
rate_limitsvalue, Claude Code isn't passing limits to status lines on your account, so there's nothing to show.
The context shows tokens, not a percentage
A chip showing “143k” instead of a ring and “72%” means dotpals knows how many tokens are in the context window, but not how big the window is. Claude Code's transcripts record the tokens but not the window size.
- Run
dotpals statusline. Claude Code gives the window size to the status line, and dotpals saves it per session (the newest 30). A session switches to a percentage after its status line refreshes. - Past 200k tokens the window must be the 1M one, so percentages show from then on anyway.
- Codex always shows percentages, because it logs the window size.
Until the size is known, the pal doesn't warn you about the context filling up, so it never raises a false alarm.
Claude Code seems stuck, with no prompt
If you've turned on Approve from the pal, Claude Code is probably waiting for your answer on the pal. While a hook runs, Claude Code doesn't show its own permission prompt.
- Answer on the pal or the notch. The notch opens by itself when there's a request, and the pal plays a double ping. If the pal is hidden, press Ctrl+Alt+P.
- Or wait. After the wait you chose (30 seconds by default), Claude asks in the terminal as usual. The card counts down.
- dotpals waits whenever something is connected to the bridge's live feed, including a dashboard or browser tab. The request itself shows on the pal and the notch.
- To wait less, choose 15 seconds in Settings → Approve from the pal, or turn it off.
“Too late: answer in the terminal” means the wait ran out, or Claude stopped waiting, before your answer arrived. Answer in the terminal.
No cards at all? Check the setting is on, and that you've restarted Claude Code since installing or updating the plugin. It works only with Claude Code sessions that send hook events.
Claude doesn't get notes about my other agents
Share with your agents only sends a note when there's something to say:
- Check it's on in Settings → Share with your agents, and restart Claude Code after installing or updating the plugin, so it loads the hook that delivers notes.
- Notes cover other sessions in a project folder with the same name, active in the last two hours, that changed files or ran tests. Sessions that only looked around aren't mentioned.
- After the first note, later prompts get one only when there's news.
- Only Claude Code can receive notes. Codex and the other agents can't.
- The hook is silent when something goes wrong. Set
DOTPALS_DEBUG=1in Claude Code's environment to see its errors.
Test connection says the TypeSafe SDK isn't installed
The Cloud (Jev) checker needs TypeSafe's SDK in the folder dotpals runs from. dotpals setup installs it, but it can be missing when setup ran offline, or when dotpals runs from a clone of the repo.
- Click Install it next to Test connection (Settings → Double-check unclear test results). It runs
npm install @typesafe-ai/sdkin the folder dotpals runs from, then tests again. - Or run
dotpals setupagain. In a clone, runnpm installin the repository. - dotpals looks for the SDK both next to the copy that's running and in the installed copy (
~/.dotpals/app), and the Claude Code plugin opens the installed copy when there is one. So afterdotpals setup, it's found whichever way the pal was started.
Clicks don't go through the pal on Linux
In small mode on Windows and macOS, clicks on the empty space around the pal go through to the window underneath. Linux can't pass clicks through a window while still telling it where the mouse is, so there the small window stays solid over its whole area.
- Drag the pal to a spot where it doesn't cover anything you click.
- Hide the pal (× or Ctrl+Alt+P) and use the notch. Its window lets clicks through everywhere except the island itself, so it stays out of the way.
The notch covers my tabs
The open notch hangs over the top of the screen, where browser tabs and title bars are. It tidies itself away:
- Move the pointer away. A notch you opened closes 8 seconds after the pointer leaves it. A shrinking line at the bottom shows the last seconds.
- Press Esc while the pointer is over it to close it at once, or click its close button.
- It opened by itself? An agent needs you, finished or failed. Done and error cards close after a few seconds. A card that needs you stays until you answer it (or close it with Esc).
- It opens as you reach for a tab? When nothing is running, the small island peeks out only after the pointer rests on the top edge for a second, and opens only when it rests on the peek too. Sliding along the top edge doesn't open it, and the peek never takes a click, so your click goes to the tab underneath. While agents work, the bar opens after you hover it for about 600 ms, so move past it rather than along it. After it closes, it won't open again until the pointer has left it.
To keep it out of the way for good, choose Notch at the top of the screen → Never in the tray menu, or run dotpals notch --off. When the pal is hidden (dotpals notch --auto) brings it back.
An agent won't connect, or its events don't arrive
- Connect is greyed out: dotpals didn't find the agent on this computer. Install it first (or check the folder with
DOTPALS_<AGENT>_DIR, see Configuration). - “Couldn't read … as JSON, so it wasn't changed”: the agent's config file has something dotpals can't parse safely, such as a trailing comma. Fix or remove it, and press Connect again.
- “The hook ran but nothing reached the bridge”: usually the hook runs plain
node(hooks added by older versions) and it isn't on thePATHthe agent uses, or the command points at a Node or a copy of dotpals that has moved. Run setup again: it rewrites the hooks of connected agents with Node's full path.dotpals doctorchecks each one. - Gemini CLI: it runs hooks from version 0.26, only in folders you've trusted, and only if hooks aren't turned off in its settings (
hooksConfig.enabled). - OpenCode: restart it after Connect. It loads plugins only when it starts.
- Cursor and Copilot CLI report tool calls when they finish, so nothing shows while a long command runs. That's expected.
- Hook commands give up quickly if dotpals isn't running, so events from while it was closed aren't recorded (Claude Code's and Codex's are filled in from their logs).
“dotpals: command not found”
Setup adds a dotpals command with npm. If that failed (setup says so), or your terminal was open before setup, open a new terminal, or run commands with npx or from the installed copy:
npx dotpals status
node ~/.dotpals/app/bin/dotpals.js status
Ctrl+Alt+P does nothing
Another app has probably claimed the shortcut first. Use the tray icon instead: click it to show or hide the pal (right-click for the menu on Windows).
No sounds or notifications
- Check 🔊 on the pal, and Sounds and Notifications in Settings (Notifications is also in the tray menu).
- In a browser, the pal can play sounds only after you've clicked the page once.
- Desktop notifications come from the desktop app, not a browser tab, and only when you're probably not looking: when the pal is hidden, a request took over a minute, or the agent has waited 20 seconds for you. Check that your system allows notifications from dotpals.
Resetting everything
To clear only your history, use Settings → History → Clear. To go back to default settings, delete ~/.dotpals/config.json and restart dotpals.
To remove dotpals completely, see Uninstalling dotpals.
Uninstalling dotpals
Go through these in order: the first steps use dotpals itself, so do them while it's still installed and running.
- Run
dotpals statusline --offif you set up the status line. - On the dashboard's Agents page, Disconnect every agent you connected. Their hook commands point at
~/.dotpals/app. - Remove the MCP server if you added it. For Claude Code, run this in the folder you added it from:
For Codex, delete theclaude mcp remove dotpals[mcp_servers.dotpals]section from itsconfig.toml:~/.codex/config.toml, or the one inCODEX_HOMEif you set that. In Cursor and other tools, delete thedotpalsserver from their MCP settings. - In the tray menu, turn off Open when I log in, then choose Quit dotpals.
- Remove the dotpals plugin in Claude Code's
/pluginmenu, or from a terminal:claude plugin uninstall dotpals@dotpals claude plugin marketplace remove dotpals - Remove the
dotpalscommand that setup added:npm uninstall -g dotpals - If you installed the app (
.exeor.dmg): on Windows, Settings → Apps → Installed apps → dotpals → Uninstall; on a Mac, drag dotpals from Applications to the Trash. - Delete the
~/.dotpalsfolder (the app, its desktop runtime, and Laya if you set it up) and the desktop app's window settings:# PowerShell (Windows) Remove-Item -Recurse -Force "$HOME\.dotpals", "$env:APPDATA\dotpals" # macOS rm -rf ~/.dotpals ~/Library/Application\ Support/dotpals # Linux rm -rf ~/.dotpals ~/.config/dotpals - Optional: delete the
.dotpals-backupcopies next to files dotpals changed, such as~/.claude/settings.json.dotpals-backup. They're the files from before dotpals touched them, and the steps above already took dotpals back out.
Your agents' own logs and settings stay as they are.
Still stuck?
Open an issue on GitHub with what you expected, what happened, your operating system, your Node version (node --version), the agent you use, and the output of dotpals status.