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 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 with dotpals start. The pal says “bridge offline, retrying…” while it can't reach the bridge.
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 set DOTPALS_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" in config.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

npm 12 and newer don't install packages straight from git unless you allow it, which is why the install 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 bridge left 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.command in ~/.claude/settings.json should end in .dotpals/app/bridge/statusline.js. If it points somewhere temporary, run dotpals statusline --off, then dotpals statusline again.
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_limits value, 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.

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=1 in 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/sdk in the folder dotpals runs from, then tests again.
Or run dotpals setup again. In a clone, run npm install in 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 after dotpals 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 that peeks out opens only when the pointer rests on it. 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 200 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 node isn't on the PATH the agent uses, or the command points at a copy of dotpals that has moved. Run setup again, then Disconnect and Connect.
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 installs dotpals in ~/.dotpals/app but doesn't put a dotpals command on your PATH. Run commands with npx or from the installed copy:

npx --allow-git=all github:rikinshah787/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:

Run dotpals statusline --off if you set up the status line.
On the dashboard's Agents page, Disconnect every agent you connected. Their hook commands point at ~/.dotpals/app.
In the tray menu, turn off Open when I log in, then choose Quit dotpals.
Remove the dotpals plugin in Claude Code's /plugin menu.

Delete the ~/.dotpals folder 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

Your agents' own logs and settings stay as they are, apart from the .dotpals-backup copies next to files dotpals changed, which you can delete.

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.