dotpals Docs

    Open source · MIT · New in 0.13: the app, and your AI agent installs it →

    See what your coding agent actually did.

    dotpals is a small floating pal that watches Claude Code, Codex or any coding agent and checks its work: what it changed, what it ran, and whether the tests really passed. When Claude breaks the tests, dotpals sends it back to fix them. And any AI tool can ask dotpals what really happened.

    npx dotpals@latest setup
    Star on GitHub
    Or ask your AI agent:
    Install dotpals for me: follow https://dotpals.vercel.app/install.md

    One command on Windows, macOS or Linux. Or paste the message into Claude Code, Codex, Cursor or any agent: it installs dotpals, connects your agents (asking first) and checks it works. Free, and your agents’ work stays on your computer. No Node.js? Download the app, or one line installs Node too. Or straight from GitHub: npx --allow-git=all github:rikinshah787/dotpals setup

    Claude · acme-web
    Codex · api-server
    my-agent · docs

    New in 0.12 Talk to Blu

    Ask about your screen. Blu answers, and draws.

    Press Ctrl+Shift+Space and talk. Blu looks at your screen when you ask about it, answers out loud, draws on it as it explains, does things on your computer and works in your apps, with the AI you already have.

    • Explains what’s on your screen. “What’s this error?” Blu answers out loud and circles what it means. Ask for it step by step and it writes the working on your screen, line by line, as it talks. Or circle something yourself (Ctrl+Alt+C) and ask.
    • Does things. “Play some jazz”, “turn it down a bit”, “make this window smaller”: music, volume, apps, pages and windows, on Windows, macOS and Linux, each one ✓ or ✗.
    • Your apps. Notion, Linear, Sentry, Google Calendar or any MCP server, connected to dotpals itself. A change waits for your yes, and nothing is ever sent, deleted or paid for.
    • Coding work, handed over and checked. “Have Claude fix the failing test”: Blu writes down what done means, Claude Code does it, and dotpals checks what really happened.
    • The AI you already have. Claude Code or Codex on your subscription, an API key, or Ollama. Blu hears you and speaks on your own computer, and Dictate (Ctrl+Alt+D) types what you say into any app.

    Everything Blu can do →

    Report card Your agents, graded

    Which agent’s work actually held up?

    A report card for your coding agents, read from what they did, not what they said. And when a request goes wrong, replay it, or rewind it.

    • Report card. Your agents side by side: code changed, tested and passed; changes never tested; tests changed to pass; claims that didn’t happen; and what the tokens bought.
    • Replay and rewind. Step through any request, with every failure and fix marked. Turn on restore points and put a request’s files back as they were: a preview first, Undo after.
    • Morning brief. The first time the pal opens each day: what your agents did since yesterday, what’s unfinished and what’s failing.
    • “It’s stuck.” A gentle ping when an agent keeps failing at the same thing, or changes a file back and forth.

    Fix loop Make agents fix failing tests

    “Done, all tests pass.” Not so fast.

    Agents say “done” in one fluent line. dotpals reads what the tests actually printed, and when Claude Code broke them, it sends Claude back to fix them before it finishes, commits or pushes.

    • Told at once, with why. “expected 3, got -1 (test/math.test.js:5)”, read from the output of Jest, Vitest, pytest, Go, Cargo and more, not just the exit code. “0 tests ran” is never a pass.
    • Sent back, not stuck. Finishing, committing or pushing while its tests fail, or after a change it didn’t test: back to work, at most twice per request. Then the pal tells you.
    • Catches the faked pass. Green only because a test lost an assertion, got a skip or now expects the wrong thing? dotpals sees it, even through sed or a script, sends Claude back once and tells you.
    • Fair. Tests that were failing before Claude changed anything are reported, not forced on it. “Run the tests and tell me” just reports. Projects without tests are never held up.
    • Your switch. On by default for Claude Code. Turn it off from the gear in the notch, or in Settings. Unclear results can still get a second opinion from Laya (on your computer) or Jev (cloud), off by default.

    The test-output rules build on claude-referee by Ismail Daşcı (MIT). Laya is by Convai Innovations; Jev is by TypeSafe.

    MCP Ask dotpals from any agent

    Every AI tool can ask what really happened.

    dotpals mcp is an MCP server. Claude Code, Codex, Cursor and other assistants ask dotpals what your agents did, and get the evidence instead of the agent’s word.

    • check_my_work. An agent asks before it says “done”: “Looks done”, or what to fix first. Codex and Cursor too, which hooks can’t hold back.
    • ready_to_merge. “Is feat/login ready?” Every check a reviewer would make, ✓ or ✗.
    • today, recap, risky_steps. Your standup, what each agent did and why its tests failed, and every force push or .env change, with the command.
    • handoff_note. Pick up a session’s work in another agent.
    claude mcp add dotpals -- npx dotpals mcp

    Codex, Cursor and others: command npx, arguments dotpals mcp. It only reads, from dotpals on your computer. All the tools →

    01 The story view

    Four hundred tool calls. Five lines.

    A single request can read dozens of files, edit a handful, run the tests, retry and push. dotpals folds all of it into a few chapters you can read in five seconds, next to what the agent says it did.

    And it flags what deserves a second look:

    • it touched .env or another file that usually holds secrets
    • it force-pushed, ran a recursive delete or threw away changes
    • the same command failed 3 times in a row

    Every step is still one click away, with the exact command, its output and the diff.

    Claude · acme-web

    You asked Add a dark mode toggle to the settings page

    Claude: Added a Dark mode toggle under Settings → Display. The choice is saved and applied on load, with a new dark.css. All tests pass.

    1. Looked through 38 filessrc/ · test/ · docs/
    2. Changed 5 files +42 −7Settings.tsx, useTheme.ts, dark.css and 2 more
    3. Tests failed twice, then passednpm test · 3 runs
    4. Installed packagesnpm install
    5. Committed and pushed“Add dark mode toggle”

    Worth a second look

    • Changed .env, which usually holds secrets
    • Force-pushed to git
    • The same command failed 3 times: “npm run e2e”

    02 The notch

    Every agent, in one island at the top of your screen.

    A slim island shows every running agent and its live plan, like 2/4 · Detecting the system setting, plus your usage limits: Claude and Codex, 5-hour and weekly, with the time each one resets.

    • Opens on hover. Out of the way until you want it.
    • Glows amber when an agent needs your OK.
    • Flashes green when an agent is done.
      Screenshot of the real notch, open: Codex needs your OK to run npm install, Claude is working on step 2 of 4, a docs session is done, and usage bars for Claude and Codex 5-hour and weekly limits.
      The real one, open.

      03 Every agent, every session

      One pal per agent, side by side.

      Setup connects Claude Code and Codex for you. Anything else connects with one JSON POST. Sessions never mix, and every Claude Code session shows up, even ones that started before dotpals was installed.

      Claude Code

      Hooks for live state, including permission prompts, plus each session's transcript, so the history is complete even if the pal opened late.

      Setup adds the plugin for you

      Codex

      Follows Codex's session logs, so the CLI, the IDE extension and the app all show up. Nothing to install on the Codex side.

      Picked up automatically

      Any other agent

      POST JSON to 127.0.0.1:5175/event from your loop, a hook script or a wrapper. Try it on the orange pal:

      The same event from a script, with a session id so it gets its own pal and tab:

      curl -s localhost:5175/event -d '{
        "session": "run-42", "harness": "my-agent",
        "state": "working", "text": "Running tests"
      }'

      04 Make your own pal

      6 bodies × 6 eyes × 9 toppers × any color.

      The same registerCustom() the dashboard uses, running live on this page. Pick, roll, then watch it think, work and celebrate.

      Pip

      Body
      Eyes
      On top
      Color

      05 The dashboard

      Sessions, logs, stats and settings.

      Every session with its requests, files and full log. Search it, copy a recap for a PR, or export to Markdown or JSON.

      The dashboard Overview: 2 requests, 4 files changed, 2 commands with 1 failed, 6 minutes of agent time, a requests-per-day chart, a by-project table and recent requests.
      • Sessions

        Every request, what you asked and what the agent said it did.

      • Logs

        Every tool call with its command, output and diff.

      • Stats

        Requests per day, files changed, commands and time by project.

      • Settings

        Your pal, sounds, notifications and how long to keep history.

      The floating window's Summary tab: what you asked, Claude's own summary, and a tally of changed files, commands and skills.
      Summary one card per request
      The Tools tab with an Edit opened, showing its diff.
      Tools every call, click for the diff
      The Files tab listing changed, new and read files.
      Files read, changed, created

      06 Local and private

      Your agents’ work stays on your computer.

      A small local server, the bridge, turns what your agents report into one activity feed. It listens only on 127.0.0.1, only answers your own computer, and sends nothing anywhere unless you turn on the cloud test check or give Blu a cloud AI.

      • History is a plain JSON file in ~/.dotpals, kept 7 days by default.
      • DOTPALS_HISTORY=0 turns history off. Clear it any time in Settings.
      • No account, no sign-up. MIT licensed, so you can read every line.
      • The MCP server only reads, from the bridge on your computer. Your AI tool asks it locally.
      • Blu hears you and speaks on your computer. What you ask it, and your screen only when you ask about it, goes to the AI you chose for Blu; with Ollama, nothing leaves.
      • The test double-check is off by default. Local (Laya) stays on your computer; Cloud (Jev) sends only an unclear run’s output, with passwords, keys and emails removed.
      • Windows
      • macOS
      • Linux

      Give your agent a pal.

      One command installs the pal, adds the Claude Code plugin if you have it, picks up Codex, and opens the dashboard. Or let your AI agent do it.

      npx dotpals@latest setup
      Star on GitHub
      Or ask your AI agent:
      Install dotpals for me: follow https://dotpals.vercel.app/install.md

      The agent follows install.md, the same steps as below, written for agents (it's a skill file too). It says what it runs, and asks before it connects another agent.

      No Node.js needed: download the app, the .exe for Windows (a setup wizard, no admin) or the .dmg for macOS. It opens a setup guide that connects your agents and tests each one on the notch, and it updates itself from GitHub. Not signed yet, so the first time click More info → Run anyway on Windows, or Open Anyway in System Settings → Privacy & Security on a Mac.

      Or let a script install Node.js first. Windows (PowerShell): irm https://dotpals.vercel.app/install.ps1 | iex · macOS and Linux: curl -fsSL https://dotpals.vercel.app/install.sh | bash

      Or download and double-click dotpals-setup.bat or dotpals-setup-mac.zip. Not signed yet, so the first time click More info → Run anyway on Windows, or Open Anyway in System Settings → Privacy & Security on a Mac.

      Or straight from GitHub: npx --allow-git=all github:rikinshah787/dotpals setup

      Only want the Claude Code plugin? /plugin marketplace add rikinshah787/dotpals then /plugin install dotpals@dotpals.