dotpals

Purpose

A coding agent reads a large number of files, edits several files, runs tests, and retries repeatedly in a single request; the chat log scrolls past, and diffs are scattered across multiple files. dotpals keeps a real-time, easy-to-understand record beside the editor, so you can answer at any time: what it changed, what it ran, whether it succeeded, whether it fixed what it broke itself, whether the current code has been tested, what it is doing now, and what was accomplished today. Its core principle is: all conclusions come from the evidence of file changes and command/test output themselves, not from the agent's own account. All data stays on your own computer, and the tool is free and open source.

Main Capabilities

• Record changes: List every file that was edited, created, or deleted, with one-click diff viewing.
• Record commands: Every command and its output, duration, and ✓/✕ status; a retry after failure is labeled "fixed on the 2nd try" or "still failed after 3 attempts".
• Make the agent fix failing tests (Claude Code, enabled by default): When a test fails, immediately tell it why (e.g. "expected 3, got -1 (test/math.test.js:5)"), and when it tries to finish, commit, or push, send it back to fix the issue, up to two times per request, after which it can stop and inform the user. Requests that do not modify code (such as "run the tests and tell me the result") only report failures; tests that were already failing before Claude made changes are only reported, and it is not forced to fix them. If the output is truncated and cannot be interpreted, the tests are rerun; if they still cannot be interpreted, the user is asked to check.
• Identify fake passes: If tests turn green only because assertions were deleted, skips were added, or expected values were changed, dotpals catches it, sends Claude back, and informs the user at the same time. Projects without tests are not blocked. This can be turned off in settings or via the gear in the Dynamic Island.
• MCP queries:dotpals mcp Lets assistants such as Claude Code, Codex, and Cursor query the real process and evidence through check_my_work、ready_to_merge、today、recap、risky_steps and more.
• Story-style presentation: Each request is presented as a few chapters such as "changed 5 files +42 −7 · tests failed twice then passed · committed and pushed", rather than hundreds of tool calls..env Changes, force pushes, the same command failing 3 times in a row, two agents editing the same file, modifying code without testing, and so on are flagged.
• Dual-agent conflict notice: When one agent is about to modify a file that another agent changed a few minutes earlier, Claude Code asks the user first, or has Claude re-read it. Other agents cannot be intercepted in advance, but the Dynamic Island and the companion inform you in real time.
• Session handoff: Continue in ▾ can hand off a session to Codex, Claude Code, or Gemini CLI, attaching the task content, completed work, test status, and remaining items in a new terminal in the same project; the description can also be copied and pasted anywhere.
• Chat with the agent (optional, disabled by default): Type text to the agent at the companion and handle permission requests and questions in place; currently supports OpenCode, with Claude Code and others to follow.
• Retry association: A retry after a failed step is shown as linked, and clicking it jumps to the corresponding attempt; the dashboard can paste a step ID (toolu_…) to open it.
• Whether it has been tested: Each session shows one line such as "tests passed · 48 passed · 7:08 PM, after the last change" or "3 files changed after 7:08 PM" or "the agent did not run tests", and states the source of the result (each test framework's own summary, or only the exit code). Zero tests or only skips are shown as "test status unclear: no real tests were run", and are never shown as passed. Optionally, this can be done by local Laya (requires Python 3.10+, one-click installation in settings or dotpals laya) or the cloud-based TypeSafe's Jev (off by default) to review uncertain results. Only tests run by the agent count.
• Simple/Detailed mode: Defaults to simple mode, summarizing each request in one sentence and showing only important warnings; detailed mode shows every section, with small steps collapsed.
• Dynamic Island: A small island at the top of the screen showing all agents, live diffs of files being edited, plans (e.g. "2/4 · Detecting the system setting"), the context window, and Claude and Codex usage limits; it opens automatically when an agent needs you, and you can allow or deny with the keyboard. After hiding the companion, it takes over; press "–" to minimize.
• Context and limits: The companion gets "worried" when the session context window is about to fill up, and "cheers" after compaction; the usage bars show the 5-hour and weekly limits and reset times (for Claude, you need to run it once dotpals statusline).
• Dashboard: View each session's requests, files, and full logs, with search and export to Markdown/JSON; it also shows the number of daily requests, time spent by project, and a live view of connected agents; settings (companion appearance, sound notifications, history retention duration or clearing) are shared between the companion and the dashboard.
• History: Retained after restart, saved locally ~/.dotpals/history.json, 7 days by default.
• Notifications and sounds: A prompt sound when an agent needs confirmation, a chime when it finishes, and a desktop notification when you're away.
• Covers all sessions and agents: All Claude Code sessions (including those started before dotpals was installed) are shown, alongside Codex and any connected agents. In compact mode, each agent has its own companion, with a round bar above indicating its identity.
• Custom companions: You can choose the body (round, boxy, fluffy, pointy, heart, or frog), eyes (dots, button, googly, pixel, visor, or shades), headwear (cat ears, horns, antenna, sprout, sparkle, bow, crown, or beret), color, and name, with thousands of combinations; you can call them in your own app via registerCustom({ name: 'Pip', shape: 'bean', eyes: 'googly', top: 'crown', color: '#16c6ae' }) and <dot-pal character="custom"> . It includes nine built-in characters, including Webby the spider hanging from a thread, who bounces down when an agent finishes.

How to use

Install with one command on Windows, macOS, or Linux; you can also install directly from GitHub:npx --allow-git=all github:rikinshah787/dotpals setup. The installer puts the desktop companion into ~/.dotpals, downloads about 100 MB of runtime (Electron, one time), adds its plugin when Claude Code is already installed, automatically detects an installed Codex, launches the companion, enables "Open at login," and opens the dashboard; Node 20 or newer is required. During installation, the terminal asks about the companion appearance, Dynamic Island, simple/detailed, approval method, test review (off, local Laya, or cloud Jev, with the key entered hidden), and so on; you can press Enter to use the defaults or run setup --yes. Common commands:dotpals mcp、dotpals dashboard、dotpals statusline（--off restore),dotpals notch --auto | --off、dotpals layaDynamic Island has four sizes: hidden when no task is running or after leaving for 3 minutes; shown as a bar while an agent is working; expanded at 640 px with two tabs, Now and Story. The approval card can be clicked Deny/Allow, or use Ctrl+Alt+N/Y (⌘⌥N/Y on macOS).

Use Cases

Suitable for developers using coding agents such as Claude Code, Codex, Cursor, and Gemini CLI, especially when concerned about situations like "the agent claims it is done but actually fails the tests," "tests were changed to green," or "multiple agents modifying the same file," to verify whether the work is truly complete and mergeable, and to quickly generate standup or PR descriptions.

Limitations

The tool is read-only monitoring and does not modify code logic; the Laya test review requires Python 3.10+, and cloud-based Jev is off by default; chatting with agents currently only supports OpenCode; other agents cannot be intercepted before modification; only tests run by agents are counted. Details on the remaining features and platforms were not provided.