Documentation
See what your coding agent actually did.
dotpals is a small floating pal that watches Claude Code, Codex or any coding agent and tells you, in plain words, what happened: which files changed, which commands ran, what failed, and what the agent says it did. Everything stays on your computer.
your agents
one activity feed
A small local server on 127.0.0.1:5175. It keeps a history in ~/.dotpals and sends nothing anywhere (unless you turn on the cloud test checker).
live
What you get
- The story, not the log. Each request reads as a few chapters, such as “Changed 5 files +42 −7”, “Tests failed twice, then passed” and “Committed and pushed”, with anything risky flagged. See the story view.
- Agents fix the tests they broke. When a test run fails, Claude Code is told why, and sent back if it tries to finish or commit while the tests fail. Tests changed just to pass are caught. See Make agents fix failing tests.
- Ask dotpals from any agent. Over MCP, Claude Code, Codex, Cursor and others can ask what your agents really did and get the evidence: is it tested, is it ready to merge. See Ask dotpals from any agent.
- Talk to Blu. Press Ctrl+Shift+Space and ask about your screen, have it play music or move a window, use your apps (Notion, Linear, Google Calendar…) with your yes for any change, or hand coding work to Claude and have it checked. It thinks with the AI you already have. See Talk to Blu.
- A live pal per agent that thinks, works, asks for your OK and celebrates, next to your editor.
- The notch: an island at the top of the screen with every agent, a live diff of what it's changing, its plan, its context window and your usage limits. It opens by itself when an agent needs you.
- A dashboard with every session, a timeline, a map of the files your agents touched, and settings.
- Every agent: Claude Code and Codex out of the box; Cursor, Gemini CLI, OpenCode and GitHub Copilot CLI with one click; anything else with one JSON POST.
Requirements
- Windows, macOS or Linux.
- Node.js 20 or newer. Setup checks this, and the one-line installers install it for you. The hook-based integrations run
node, so Node has to be on yourPATH. - About 100 MB for the desktop runtime (Electron), downloaded once into
~/.dotpals. Without it you can still use the pal and the dashboard in a browser. - For Blu, the desktop app, a microphone, and an AI for its brain: Claude Code or Codex, an API key, or Ollama. Its speech models (about 400 MB with the usual Hearing) download the first time you talk.
- An agent: Claude Code, Codex, Cursor, Gemini CLI 0.26 or newer, OpenCode, GitHub Copilot CLI, or anything that can send an HTTP request.
Install
Ask your AI agent. Paste this into Claude Code, Codex, Cursor or any agent that can run commands:
Install dotpals for me: follow https://dotpals.vercel.app/install.md
It follows install.md: it checks for Node.js, runs the setup below with the defaults, runs dotpals doctor, offers to connect your other agents (asking before it changes their config, through the agents API) and tells you what it did. Without Node.js it offers the app instead. The file is a skill too: save it as ~/.claude/skills/install-dotpals/SKILL.md and /install-dotpals does the same.
The app, no Node.js needed. From the latest release, download dotpals-setup-<version>-x64.exe for Windows (-arm64.exe on ARM; a setup wizard, no admin, installs for you only) or dotpals-<version>-mac-arm64.dmg for macOS (-mac-x64.dmg on Intel Macs; drag dotpals to Applications). The first time it starts it does what setup below does, with the defaults, then opens a setup guide that lists the agents on your computer, connects each one and tests it (a pal says hello on the notch; Set up agents… in the dotpals menu opens it again); what it did is in ~/.dotpals/setup.log. It isn't signed yet, so the first time Windows says “Windows protected your PC” (click More info, then Run anyway), and macOS won't open it until you allow it (System Settings → Privacy & Security → Open Anyway). It updates itself: once a day it checks GitHub, downloads a newer version in the background and installs it when dotpals quits (or right away, from the notification). The dotpals command is in ~/.dotpals/bin. Without Node.js, Claude Code's sessions still show (dotpals reads its transcripts), but approvals from the pal, the file guard and the fix loop come with the Claude Code plugin, whose hooks need Node.js. See The downloaded app.
Or one command, on any platform, with Node.js:
npx dotpals@latest setup
No Node.js yet? These install it first (Node.js LTS, for every app), then run the same setup. On Windows, in PowerShell:
irm https://dotpals.vercel.app/install.ps1 | iex
On macOS (Homebrew if you have it, otherwise the official installer from nodejs.org, which asks for your password) or Linux (where it says how to install Node.js if you need it):
curl -fsSL https://dotpals.vercel.app/install.sh | bash
Or download and double-click dotpals-setup.bat (Windows) or dotpals-setup-mac.zip (macOS: open the zip, then dotpals-setup.command) from the latest release. They aren't signed yet, so the first time Windows says “Windows protected your PC” (click More info, then Run anyway) and macOS says it can't check the file (System Settings → Privacy & Security → Open Anyway). If an installer stops, see The one-line installer stops.
Setup:
- checks that Node is version 20 or newer,
- copies dotpals to
~/.dotpals/app, a permanent home (npx runs from a temporary folder), - downloads the desktop runtime (Electron, about 100 MB) into
~/.dotpals, once, - creates the settings file,
~/.dotpals/config.json(anything you haven't set uses its default), - adds the Claude Code plugin, if the
claudecommand is installed, - checks for Codex (
~/.codex). There's nothing to install for it, - starts the pal, turns on Open when I log in, and opens the dashboard.
| Option | What it does |
|---|---|
--no-claude | Don't add the Claude Code plugin. |
--no-login | Don't start dotpals when you log in. |
--no-start | Install only; don't start the pal or open the dashboard. |
For example:
npx dotpals@latest setup --no-login
To install straight from GitHub instead of npm (for example to try a branch: github:rikinshah787/dotpals#branch): npx --allow-git=all github:rikinshah787/dotpals setup. The --allow-git=all flag lets npm 12 and newer install from git; older versions ignore it.
To update, run the same command again. It replaces ~/.dotpals/app and keeps your settings and history.
If Electron can't be installed, setup says so, starts only the bridge and opens the dashboard in your browser. See Without the desktop app.
Only the Claude Code plugin
If you only use Claude Code, you can install dotpals from inside it instead:
/plugin marketplace add rikinshah787/dotpals
/plugin install dotpals@dotpals
Restart Claude Code, then run:
/dotpals:pals
The first time, it offers to download the desktop window's runtime (Electron, about 100 MB, into ~/.dotpals). If you'd rather not, it starts the bridge and opens the pal in your browser at http://localhost:5175. In that case you can name a pal: /dotpals:pals grok.
After that, the pal opens by itself whenever a Claude Code session starts or you send a prompt and it isn't already running. Set DOTPALS_AUTOSTART=0 to turn that off (see Configuration).
First run
The pal's window appears in the bottom-right corner of your screen, above your other windows, with “Waiting for your agent…”. Then:
- Restart Claude Code if it was open during setup, so it loads the plugin. (Its sessions show up from their transcripts anyway, a second or two behind.)
- Send your agent a prompt. A pal appears and thinks, works, asks for your OK and celebrates as the agent does.
- Read the Summary tab. One card per request: what you asked, what the agent said it did, and the story of what happened. Tools lists every tool call, and Files every file read or changed, with diffs.
| Control | What it does |
|---|---|
| Ctrl+Alt+P (⌘⌥P on macOS) | Show or hide the pal from anywhere. |
| Drag the pal | Move the window. It remembers where you put it. |
| ▦ | Open the dashboard. |
| ⤡ | Switch between just the pal (small mode) and the full view. |
| × | Hide the pal. The notch takes over at the top of the screen. |
| 🔊 | Sounds on or off. |
| The pal menu | Choose your first pal. More sessions get the next characters. |
| Tray icon | Show or hide, Just the pal, Notch at the top of the screen, Dashboard, Notifications, Open when I log in and Quit dotpals. |
Then, if you like:
- Connect Cursor, Gemini CLI, OpenCode or GitHub Copilot CLI on the dashboard's Agents page. See Agents.
- See Claude Code's usage limits in the notch by running
dotpals statuslineonce. See Usage limits. - Make your own pal in the dashboard's Settings. See Make your own pal.
Running dotpals commands
Setup installs dotpals in ~/.dotpals/app and adds a dotpals command. If your terminal can't find it, run commands the same way as setup, or with Node from the installed copy:
npx dotpals status
# or, from the installed copy
node ~/.dotpals/app/bin/dotpals.js status
In PowerShell, use node "$HOME\.dotpals\app\bin\dotpals.js" status. The rest of these docs write dotpals <command> for short. Every command is on the CLI page.
Without the desktop app
The bridge on its own serves everything in a browser, which is handy on a machine without a desktop, or if you'd rather not install Electron:
dotpals bridge
http://127.0.0.1:5175/is the pal, with the same Summary, Tools and Files tabs. Pop out ↗ floats it above other windows in Chrome or Edge 116 and newer.http://127.0.0.1:5175/dashboardis the dashboard.
The notch, desktop notifications, click-through and the tray need the desktop app. Browsers also play sounds only after you've clicked the page once.