Skip to content
Back to search

dotpals

See what your coding agent actually did. A desktop pal and notch for Claude Code, Codex, Cursor, Gemini CLI and any agent: files changed, commands run and tests checked, in plain words.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Rikinshah787/dotpals with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Rikinshah787/dotpals'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rikinshah787--dotpals/badge.svg)](/listings/rikinshah787--dotpals)

HTML

<a href="/listings/rikinshah787--dotpals"><img src="/api/listings/rikinshah787--dotpals/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One command

npx dotpals@latest setup

(Needs Node 20 or newer. To install straight from GitHub instead: `npx --allow-git=all github:rikinshah787/dotpals setup`.)

That's all. It:

1. installs the desktop pal in `~/.dotpals`, and downloads its runtime (Electron, about 100 MB, once), 2. adds the Claude Code plugin, if Claude Code is installed, 3. picks up Codex automatically, if it's installed, 4. starts the pal, turns on *open when I log in*, and opens the dashboard.

Options: `--no-claude` (skip the plugin), `--no-login` (don't start at login) and `--no-start`. Run it again any time to update.

Only the Claude Code plugin

/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. After that, the pal opens by itself whenever a Claude Code session starts.

Codex

There's nothing to install on the Codex side. dotpals follows Codex's session logs (`~/.codex/sessions`), so the Codex CLI, IDE extension and app all show up while the pal is running. The one-command setup starts it at login.

Cursor, Gemini CLI, OpenCode and GitHub Copilot CLI

Open the dashboard's **Agents** page and press **Connect** on the agent you use. Each card shows whether the agent is installed, whether it's connected, and when its last event arrived.

- **Connect** adds one small command, or a plugin for OpenCode, to that agent's own config. It backs up the original first, merges instead of overwriting, and leaves a file it can't read untouched. - **Disconnect** takes out only what dotpals added. - **Send a test event** runs the real command. If it reaches dotpals, a pal says hello. - The switch on each card turns an agent off without disconnecting it.

The Connect button changes these files:

| Agent | What Connect changes | | ----- | -------------------- | | Cursor | `~/.cursor/hooks.json`. Cursor reloads it on save | | Gemini CLI | `~/.gemini/settings.json` (Gemini CLI 0.26 or newer, in folders you've trusted) | | OpenCode | adds `~/.config/opencode/plugins/dotpals.js`. Restart OpenCode to load it | | GitHub Copilot CLI | adds `~/.copilot/hooks/dotpals.json` |

Any other agent

Send JSON to the local bridge from your agent loop, a hook script or a wrapper. See [Plug in any agent](#plug-in-any-agent).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "dotpals",
  3. "owner": {
  4. "name": "dotpals contributors"
  5. },
  6. "description": "Fluffy animated pals that check what your Claude Code sessions really did, and make Claude fix the tests it broke.",
  7. "plugins": [
  8. {
  9. "name": "dotpals",
  10. "source": "./",
  11. "description": "A floating pal that checks every change, command and test result your agent makes, live, and sends Claude back to fix the tests it broke."
  12. }
  13. ]
  14. }
README.md · README · 329 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="desktop/icon.png" width="96" alt="">
  3. # dotpals
  4. **See what your coding agent actually did.**
  5. A small floating pal that watches Claude Code, Codex or any agent and checks its work: which files changed, which commands ran, and whether the tests really passed, read from their output, not the agent's word. When Claude breaks the tests, dotpals sends it back to fix them. Any AI tool can ask dotpals what really happened. And now you can talk to it: **Blu** sees your screen, draws on it as it explains, and uses your apps.
  6. ```bash
  7. npx dotpals@latest setup
  8. ```
  9. **Or ask your AI agent:** `Install dotpals for me: follow https://dotpals.vercel.app/install.md`<br>
  10. **No Node.js?** [Download the app](https://github.com/Rikinshah787/dotpals/releases/latest) for Windows or macOS.
  11. <sub>Windows, macOS or Linux. Free, open source, and your agents’ work stays on your computer. [All the ways to install](#install).</sub>
  12. [![CI](https://github.com/rikinshah787/dotpals/actions/workflows/ci.yml/badge.svg)](https://github.com/rikinshah787/dotpals/actions/workflows/ci.yml)
  13. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  14. ![Works with Claude Code and Codex](https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20any%20agent-d97757)
  15. **[Install](#install)** · **[Talk to Blu](#talk-to-blu)** · **[Features](#features)** · **[Plug in any agent](#plug-in-any-agent)** · **[Docs](https://dotpals.vercel.app/guide/)**
  16. **[⭐ Star dotpals](https://github.com/Rikinshah787/dotpals/stargazers)** if your agent ever said "Done!" and you weren't sure · **[Tell us what's confusing](https://github.com/Rikinshah787/dotpals/issues/new)**
  17. </div>
  18. ## New in 0.13: the app, and your agent installs it
  19. - **Download, double-click, done.** A Windows setup wizard and a macOS disk image, no Node.js needed. A setup guide connects your agents and tests each one, and the app updates itself from GitHub.
  20. - **Or ask your AI agent.** Paste `Install dotpals for me: follow https://dotpals.vercel.app/install.md` into Claude Code, Codex, Cursor or any agent. It installs dotpals, connects your other agents (asking first) and checks it works.
  21. ## New in 0.12: Talk to Blu
  22. <p align="center"><img src="docs/blu.gif" width="760" alt="You say: Blu, explain this chart simply, and circle the best month. Blu looks at the screen, answers in the notch at the top (each bar is one month, and sales mostly climb toward the end of the year), and draws a red circle around November, the best month"></p>
  23. Press **Ctrl+Shift+Space** and talk. Blu is the pal in your notch:
  24. - **It explains 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.
  25. - **It does things.** "Play some jazz", "turn it down a bit", "make this window smaller". Each one shows ✓ or ✗.
  26. - **It uses your apps.** Notion, Linear, Sentry, Google Calendar or any MCP server. A change waits for your yes; nothing is ever sent, deleted or paid for.
  27. - **It hands coding work to Claude and checks it.** "Have Claude fix the failing test": Blu writes down what done means, Claude Code does it, and dotpals checks what really happened.
  28. - **It runs on the AI you already have.** Claude Code or Codex on your subscription, an API key, or Ollama. Hearing and Blu's voice run on your computer.
  29. More in [Talk to Blu](#talk-to-blu). 0.11 brought the report card, replay and rewind, the morning brief and "It's stuck"; all of it is in the [changelog](CHANGELOG.md).
  30. ## Why
  31. Coding agents do a lot in a single request: they read dozens of files, edit a handful, run tests, retry and search. The chat scrolls by and the diff is spread across files. dotpals keeps a live, plain-language record next to your editor, so you can always answer:
  32. - **What did it change?** Every file edited, created or deleted, with the diff one click away.
  33. - **What did it run, and did it work?** Every command with its output, and **fixed on try 2** or **still failing after 3 tries**.
  34. - **Did it fix what it broke?** Claude Code is sent back when its tests fail, and a test changed just to make it pass is caught.
  35. - **Is the code as it is now tested?** "Changed 2 files after the tests passed: not tested since" is impossible to miss.
  36. - **What did I get done today?** A running tally, copied as Markdown for a standup or PR in one click.
  37. <div align="center">
  38. <img src="docs/demo.gif" width="760" alt="The dotpals notch catches a faked pass: Claude Code's change breaks a test, it edits the test to expect the wrong answer, dotpals sees the test was changed and sends it back, and Claude puts the test back and fixes the code">
  39. <sub>🔊 <a href="https://github.com/Rikinshah787/dotpals/releases/download/v0.9.0/dotpals-launch-1080p.mp4">Watch the launch video with sound (47 s, 1080p)</a> · <a href="https://github.com/Rikinshah787/dotpals/releases/download/v0.9.0/dotpals-launch-square.mp4">square cut</a></sub>
  40. </div>
  41. ## Features
  42. - **Project rules for every agent**: put a `.dotpals.json` in a project (`{ "mustNotTouch": ["migrations"], "onlyTouch": ["src", "test"], "mustPass": ["npm test"], "noNewDependencies": true }`) and every request there is held to it, whichever agent makes it: what it broke shows on its card and in *Ready to merge?* and `check_my_work`. Claude Code is asked before an edit a rule forbids (`"beforeEdit": "ask"`, `"tell"` or `"off"`). Paths take `*`, `**` and `?`; the nearest file from the agent's folder up to the repository's root wins, so a monorepo's package can have its own.
  43. - **Make agents fix failing tests** (Claude Code, on by default): finishing, committing or pushing while its tests fail, or before it tested its last change, sends Claude back to fix them, at most twice per request. A test faked to pass (an assertion taken out, a skip added, an expectation changed) is caught too.
  44. - **Was it tested?** Results are read from the test output itself (jest, vitest, pytest, go, cargo, dotnet, Maven, Gradle, RSpec and more), never just the exit code. "0 tests ran" is never a pass.
  45. - **Report card**: your agents side by side: changes tested and passed, changes never tested, tests changed to pass, claims that didn't happen, and what the tokens bought.
  46. - **Replay and rewind**: step through any request, and (with restore points on) put its files back as they were.
  47. - **Morning brief and "It's stuck"**: what your agents did since yesterday, and a ping when one keeps failing at the same thing.
  48. - **The story, not the log**: each request reads as a few chapters (*Changed 5 files · Tests failed twice, then passed · Committed and pushed*), with anything risky flagged: `.env` changed, a force-push, two agents editing the same file.
  49. - **Ask dotpals from any agent**: an [MCP server](#ask-dotpals-from-any-agent-mcp), so Claude Code, Codex, Cursor and others can check their work against what really happened.
  50. - **The notch**: every agent in one island at the top of your screen, with a live diff, its plan, its context window and your usage limits. It opens when an agent needs your OK, and **Ctrl+Alt+Y** / **Ctrl+Alt+N** answer it.
  51. - **Hand-off**: **Continue in ▾** hands a session to Codex, Claude Code or Gemini CLI with a note on what was done and what's left.
  52. - **Dashboard**: every session with its requests, files and full log, search, stats, and export to Markdown or JSON.
  53. - **A pal with personality**: nine characters that think, work, wait, celebrate and sulk, or [make your own](#make-your-own-pal).
  54. <p align="center">
  55. <img src="docs/notch.png" width="420" alt="The notch, open on the Now tab: Claude's pal on the left, a live diff of Settings.tsx typing in, its plan at step 2 of 4, its context window, three helpers, and usage bars for Claude and Codex">
  56. &nbsp;
  57. <img src="docs/summary.png" width="250" alt="The dotpals window: a blue pal above a Summary card listing a request, Claude's own summary, and a tally of changed files, commands and skills">
  58. </p>
  59. Every feature, in detail: **[the guide](https://dotpals.vercel.app/guide/features.html)**.
  60. ## Talk to Blu
  61. | Keys | What happens |
  62. | --- | --- |
  63. | **Ctrl+Shift+Space** (⌘⇧Space on macOS) | **Talk.** The notch opens and Blu listens. On Windows, hold the keys while you talk; or tap them and Blu listens until you pause |
  64. | **Ctrl+Alt+C** (⌃⌥C) | **Circle and ask.** Draw around anything on screen, then ask about it |
  65. | **Ctrl+Alt+D** (⌃⌥D) | **Dictate.** Say it, and it's typed where your cursor is |
  66. Things to say:
  67. - "What's this error?" · "Explain this step by step" · "Circle the button I need"
  68. - "Play some jazz" · "Turn it down a bit" · "Put Spotify on the left half"
  69. - "What's on my calendar today?" · "Create a page called Weekly plan in Notion"
  70. - "Have Claude fix the failing test" · "What are my agents doing?" · "Stop"
  71. **Set it up** in Dashboard → Settings:
  72. - **Blu → Blu's brain**: Claude Code or Codex on your subscription, an API key (Anthropic, OpenAI, Gemini, OpenRouter), or Ollama on your computer.
  73. - **Apps**: Notion, Linear and Sentry in one click, Google Calendar with your own sign-in client, or any MCP server by its address or command.
  74. - **Blu → Shortcuts**: your own keys.
  75. The first time you talk, dotpals downloads a speech model (about 80 MB) and Blu's voice (about 330 MB), once. Both run on your computer.
  76. **What Blu won't do without you:**
  77. - Change anything in your apps before you say yes. Even then it never sends, deletes or pays for anything.
  78. - Click, type or press keys, unless you turn that on.
  79. - Send coding work to an agent before you say "send it".
  80. What it does on your computer is a fixed list, checked again before it runs. It never follows instructions written on your screen.
  81. **Your privacy.** Your voice stays on your computer. A screenshot goes to Blu's brain only when you ask about the screen, or circle something. With Ollama, nothing leaves your computer at all.
  82. Blu is tested on Windows. macOS (through dotpals.app, so permissions are asked in dotpals' name) and Linux (X11, with `playerctl`, `pactl` and `xdotool`) are new since 0.12. **[Everything about Blu →](https://dotpals.vercel.app/guide/features.html#blu)**
  83. ## Make your own pal
  84. <p align="center"><img src="docs/custom-pals.png" width="640" alt="Eighteen home-made pals: round, boxy, fluffy, pointy, heart and frog bodies in different colors, with googly eyes, visors, pixel eyes and shades, and sprouts, crowns, horns, bows, antennas and berets on top"></p>
  85. Dashboard → **Settings → Make your own pal**: pick a body, eyes, something on top, any color and a name. Thousands of combinations, or **Surprise me**.
  86. ## Install
  87. Three ways in. They all end the same: the pal on your screen, the notch at the top, and Claude Code and Codex connected.
  88. ### Ask your AI agent
  89. Paste this into Claude Code, Codex, Cursor or any agent that can run commands:
  90. ```text
  91. Install dotpals for me: follow https://dotpals.vercel.app/install.md
  92. ```
  93. It checks for Node, runs the setup below, runs `dotpals doctor`, offers to connect your other agents (asking before it changes their config) and tells you what it did. [install.md](site/install.md) is also a skill file: save it as `~/.claude/skills/install-dotpals/SKILL.md` and `/install-dotpals` does the same.
  94. ### Download the app (no Node.js)
  95. From the [latest release](https://github.com/Rikinshah787/dotpals/releases/latest):
  96. - **Windows:** `dotpals-setup-<version>-x64.exe` (`-arm64.exe` on ARM), a setup wizard: pick a folder, desktop and Start menu shortcuts, no admin.
  97. - **macOS:** `dotpals-<version>-mac-arm64.dmg` (`-mac-x64.dmg` on Intel Macs); drag dotpals into Applications.
  98. - **First start:** it sets everything up like the command below does, and opens a setup guide that lists the agents on your computer, connects each one and tests it (a pal says hello on the notch). The guide is in the dotpals menu (**Set up agents…**); its setup log is in `~/.dotpals/setup.log`.
  99. - **Not signed yet:** on Windows click **More info → Run anyway**; on a Mac open it once, then System Settings → Privacy & Security → **Open Anyway**.
  100. - **Updates itself from GitHub:** a newer version downloads in the background and installs when dotpals quits (or right away, from the notification).
  101. - The `dotpals` command is in `~/.dotpals/bin` (add it to your PATH if you want it in every terminal). Without Node, Claude Code's sessions still show (read from its transcripts); approvals from the pal, the file guard and the fix loop need the Claude Code plugin, which needs Node.
  102. ### One command (Node.js 20 or newer)
  103. ```bash
  104. npx dotpals@latest setup
  105. ```
  106. No Node.js? These install it first (Node.js LTS, for every app), then run the same setup:
  107. ```powershell
  108. # Windows (PowerShell)
  109. irm https://dotpals.vercel.app/install.ps1 | iex
  110. ```
  111. ```bash
  112. # macOS (Homebrew, or the official installer from nodejs.org, which asks for your password) and Linux
  113. curl -fsSL https://dotpals.vercel.app/install.sh | bash
  114. ```
  115. Or download `dotpals-setup.bat` (Windows) or `dotpals-setup-mac.zip` (macOS) from the [latest release](https://github.com/Rikinshah787/dotpals/releases/latest) and double-click it. They aren't signed yet, so the first time Windows says "Windows protected your PC" (More info → Run anyway) and macOS says it can't check the file (System Settings → Privacy & Security → Open Anyway). On Linux the installer tells you how to get Node if you need it.
  116. Setup installs the desktop pal in `~/.dotpals` (with its runtime, Electron, about 100 MB, once), adds the Claude Code plugin if you have Claude Code, picks up Codex, starts the pal at login and opens the dashboard. Run it again any time to update. Options: `--yes` (no questions, keep the defaults), `--no-claude`, `--no-login`, `--no-start`, `--no-path`. Straight from GitHub instead of npm: `npx --allow-git=all github:rikinshah787/dotpals setup`.
  117. ### Your other agents
  118. - **Only the Claude Code plugin:** `/plugin marketplace add rikinshah787/dotpals`, then `/plugin install dotpals@dotpals`, restart Claude Code and run `/dotpals:pals`.
  119. - **Codex:** nothing to install. dotpals follows Codex's session logs while the pal is running.
  120. - **Cursor, Gemini CLI, OpenCode and GitHub Copilot CLI:** press **Connect** on the dashboard's **Agents** page. It backs up the agent's config first, and **Disconnect** takes out only what it added.
  121. - **Any other agent:** see [Plug in any agent](#plug-in-any-agent).
  122. ## Using it
  123. | | |
  124. | --- | --- |
  125. | **Ctrl+Alt+P** (⌘⌥P on macOS) | Show or hide the pal |
  126. | **Ctrl+Shift+Space** · **Ctrl+Alt+C** · **Ctrl+Alt+D** | Talk to Blu · circle and ask · dictate |
  127. | **▦** | The dashboard: sessions, logs, stats and settings |
  128. | **–** | Minimize to the tray (the notch keeps watching) |
  129. ```bash
  130. dotpals start # open the floating pal
  131. dotpals dashboard # open the dashboard
  132. dotpals status # what's running and connected
  133. dotpals doctor # no pal, notch or agents? checks, fixes what it can, says what to run for the rest
  134. dotpals mcp # the MCP server (below)
  135. ```
  136. To uninstall (the hooks, the MCP server, the `dotpals` command, the app and `~/.dotpals`), follow **[Uninstalling dotpals](https://dotpals.vercel.app/guide/troubleshooting.html#uninstall)**.
  137. ## Ask dotpals from any agent (MCP)
  138. `dotpals mcp` is an [MCP](https://modelcontextprotocol.io) server: Claude Code, Codex, Cursor and other assistants ask dotpals what your agents really did, and get the evidence instead of the agent's word. It only reads, from the pal running on this computer.
  139. ```bash
  140. claude mcp add dotpals -- npx dotpals mcp
  141. ```
  142. Codex and Cursor: command `npx`, arguments `dotpals mcp` (for Codex, under `[mcp_servers.dotpals]` in `~/.codex/config.toml`).
  143. | Tool | Answers |
  144. | --- | --- |
  145. | `check_my_work` | For the agent itself, before it says "done": "Looks done", or what to fix first |
  146. | `ready_to_merge` | The checks a reviewer would make: tests ran after the last change and passed (not because the tests were changed), nothing risky, committed |
  147. | `test_status` | Is it really tested, and why the last run failed ("expected 3, got -1") |
  148. | `agents_now` · `today` · `recap` | What each agent is doing, did today, or did request by request |
  149. | `report_card` · `brief` | The agents side by side, and the morning brief or weekly recap |
  150. | `risky_steps` · `handoff_note` | Force pushes, `.env` changes and more; a note for another agent to pick up a session |
  151. ## Privacy
  152. Your agents' work stays on your computer. The bridge listens only on `127.0.0.1`, reads Claude Code's and Codex's logs locally, and sends nothing anywhere. The exceptions are your choice:
  153. - **Blu**: what you say goes to the AI you picked for Blu's brain (nowhere, with Ollama), with a screenshot only when you ask about the screen.
  154. - **Cloud (Jev)** test double-check, off by default: an unclear test run's output, with passwords, keys and emails removed.
  155. History is a plain JSON file in `~/.dotpals` (`DOTPALS_HISTORY=0` turns it off). See [SECURITY.md](SECURITY.md) and the [privacy guide](https://dotpals.vercel.app/guide/privacy.html).
  156. ## How accurate is it?
  157. We check. `test/accuracy/cases` holds 36 real requests, and every claim dotpals made about them was checked by hand against what really happened:
  158. | Claim | Claims | Right | Wrong | Unsure |
  159. |---|---:|---:|---:|---:|
  160. | Test results (passed, failed) | 99 | 91 | 1 | 7 |
  161. | Risky steps | 14 | 14 | 0 | 0 |
  162. | Retries ("fixed on try 2") | 15 | 14 | 1 | 0 |
  163. | Ready to merge? | 36 | 35 | 1 | 0 |
  164. | Why it stopped | 36 | 35 | 1 | 0 |
  165. | What changed (git) | 10 | 9 | 1 | 0 |
  166. | Tests changed to pass | 20 | 20 | 0 | 0 |
  167. | Why tests failed | 25 | 25 | 0 | 0 |
  168. | **All** | **255** | **243 (95.3%)** | **5** | **7** |
  169. "Unsure" is a missing answer, not a false one. `npm run accuracy` lists the 5 wrong ones, and the test suite fails if a right claim turns wrong.
  170. ## How it works
  171. ```
  172. Claude Code ── hooks + transcripts ┐
  173. Codex ──────── session logs ───────┼──▶ bridge (127.0.0.1:5175) ──▶ pal · notch · dashboard · MCP
  174. your agent ─── POST /event ────────┘ one activity model
  175. ```
  176. Your agents report what they do. A small local server, the bridge, turns it into one activity feed and keeps history in `~/.dotpals`. The pal, the notch and the dashboard show it live. Contributors: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  177. ## Plug in any agent
  178. | Agent | How it connects |
  179. | ------- | --------------- |
  180. | **Claude Code** | Hooks for live state and permission prompts, plus the session transcript |
  181. | **Codex** (CLI, IDE extension, app) | Its session logs in `~/.codex/sessions`; nothing to set up |
  182. | **Cursor**, **Gemini CLI**, **OpenCode**, **GitHub Copilot CLI** | **Connect** on the dashboard's Agents page |
  183. | **Anything else** | POST JSON to `http://127.0.0.1:5175/event` |
  184. ```bash
  185. curl -s localhost:5175/event -d '{
  186. "session": "run-42", "harness": "my-agent", "state": "working", "text": "Running tests",
  187. "activity": { "id": "call-1", "kind": "run", "title": "Run the tests", "status": "running",
  188. "body": { "command": "npm test" } }
  189. }'
  190. ```
  191. Send the same `id` again with `"status": "ok"` when it finishes. The Agents page has copy-paste snippets for curl, PowerShell, Node, Python and the shell. The full event format: **[the guide](https://dotpals.vercel.app/guide/agents.html#any-agent)**.
  192. ## Use the pal in your own app
  193. The pal is a dependency-free Web Component, `<dot-pal>`, for chat UIs, IDE panels and dashboards. It works in plain HTML, React, Vue, Svelte, Angular, Electron and VS Code webviews.
  194. ```html
  195. <script type="module" src="https://unpkg.com/dotpals"></script>
  196. <dot-pal id="agent" character="grok"></dot-pal>
  197. <script type="module">
  198. const pal = document.getElementById('agent');
  199. pal.setState('thinking');
  200. pal.setState('working', { text: 'Running tests…' });
  201. pal.setState('done', { text: 'All green!' });
  202. </script>
  203. ```
  204. Or `npm install dotpals`, then `import 'dotpals'`. States, characters, attributes, events, styling and your own characters: **[the component guide](https://dotpals.vercel.app/guide/component.html)**.
  205. ## Documentation
  206. The full guide is at **[dotpals.vercel.app/guide](https://dotpals.vercel.app/guide/)**: every feature, Blu, each agent, the CLI, configuration, the bridge's HTTP API, the `<dot-pal>` component, privacy and troubleshooting. Its source is in [`site/guide/`](site/guide).
  207. ## Roadmap
  208. - **More agents**: Windsurf, Cline, Aider and others, as each gets a documented way in.
  209. - Signing the Windows and macOS app, so it opens without a warning the first time.
  210. Ideas and pull requests are welcome. Open an [issue](https://github.com/rikinshah787/dotpals/issues) to discuss.
  211. ## Contributing
  212. ```bash
  213. npm install # dev only: Electron for the desktop window
  214. npm test # node --test, no dependencies needed
  215. npm run float # the desktop pal
  216. npm run dashboard # the dashboard
  217. ```
  218. See [CONTRIBUTING.md](CONTRIBUTING.md). To support a new agent, add an adapter next to [`bridge/adapters/codex.js`](bridge/adapters/codex.js).
  219. ## Credits
  220. - Reading test results and double-checking unclear ones builds on [claude-referee](https://github.com/ismaildasci/claude-referee) by Ismail Dasci (MIT): its test-output parsers, redaction rules and "done" question are adapted in `bridge/ui/testout.js`, `bridge/redact.js` and `bridge/checker.js`. See [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES).
  221. - The optional checkers are [Laya](https://huggingface.co/convaiinnovations/laya) by Convai Innovations (runs on your computer; dotpals installs it from PyPI when you click Set up Laya) and [TypeSafe](https://typesafe.ai)'s Jev, through its MIT-licensed SDK `@typesafe-ai/sdk`.
  222. ## Trademarks
  223. Character names are playful nicknames. dotpals is not affiliated with or endorsed by Anthropic, OpenAI or any other AI company, and the characters are original artwork, not logos.
  224. ## License
  225. [MIT](./LICENSE)
installers/dotpals-setup.bat · Bundled script · 14 lines · 1 finding marked
  1. @echo off
  2. setlocal
  3. REM Double-click to install dotpals on Windows. It runs the one-line installer,
  4. REM https://dotpals.vercel.app/install.ps1, which installs Node.js LTS
  5. REM if you need it (from nodejs.org), then dotpals (from npm).
  6. REM
  7. REM This file isn't signed yet, so the first time Windows SmartScreen may say
  8. REM "Windows protected your PC": click More info, then Run anyway.
  9. powershell -NoProfile -ExecutionPolicy Bypass -Command "[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072; $ErrorActionPreference = 'Stop'; irm https://dotpals.vercel.app/install.ps1 | iex; exit $LASTEXITCODE"
  10. set DOTPALS_EXIT=%ERRORLEVEL%
  11. echo.
  12. pause
  13. exit /b %DOTPALS_EXIT%
site/install.ps1 · Bundled script · 102 lines · 1 finding marked
  1. # dotpals installer for Windows (PowerShell 5.1 or newer).
  2. #
  3. # irm https://dotpals.vercel.app/install.ps1 | iex
    • Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
    • Line 3 on GitHub
  4. #
  5. # If Node.js 20 or newer isn't installed, it installs Node.js LTS for every app on
  6. # this PC (with winget, or the official installer from nodejs.org), then runs
  7. # `npx --yes dotpals@latest setup`. It only downloads from nodejs.org and npm.
  8. # Everything runs inside a function, so `| iex` never closes your PowerShell window.
  9. function Install-Dotpals {
  10. $ErrorActionPreference = 'Stop'
  11. $ProgressPreference = 'SilentlyContinue' # Windows PowerShell downloads crawl with the progress bar on
  12. [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
  13. $help = 'https://dotpals.vercel.app/guide/troubleshooting.html#installer'
  14. function Step($text) { Write-Host ''; Write-Host "-> $text" -ForegroundColor Cyan }
  15. function Ok($text) { Write-Host " $text" -ForegroundColor Green }
  16. function Fail($text) {
  17. Write-Host ''
  18. Write-Host "x $text" -ForegroundColor Red
  19. Write-Host " What to do next: $help"
  20. $global:LASTEXITCODE = 1
  21. }
  22. # Node's major version, or 0 when there's none.
  23. function Get-NodeMajor {
  24. if (-not (Get-Command node -ErrorAction SilentlyContinue)) { return 0 }
  25. try { $version = & node --version } catch { return 0 }
  26. if ($version -match '^v(\d+)\.') { return [int]$Matches[1] }
  27. return 0
  28. }
  29. # Installers change PATH for new windows only. Read it again so node and npx work here now,
  30. # from the same place every other app (and your agents' hooks) will find them.
  31. function Update-Path {
  32. $machine = [Environment]::GetEnvironmentVariable('Path', 'Machine')
  33. $user = [Environment]::GetEnvironmentVariable('Path', 'User')
  34. # The saved PATH first (where a new Node.js just went), then this window's own extra folders (version managers' shims).
  35. $saved = "$machine;$user" -split ';' | Where-Object { $_ }
  36. $extra = $env:Path -split ';' | Where-Object { $_ -and ($saved -notcontains $_) }
  37. $env:Path = (@($saved) + @($extra)) -join ';'
  38. }
  39. function Install-NodeWithWinget {
  40. if (-not (Get-Command winget -ErrorAction SilentlyContinue)) { return }
  41. Step 'Installing Node.js LTS with winget. Windows may ask for permission.'
  42. & winget install --id OpenJS.NodeJS.LTS -e --silent --accept-source-agreements --accept-package-agreements
  43. Update-Path
  44. }
  45. function Install-NodeFromNodejsOrg {
  46. $arch = 'x64'
  47. if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64' -or $env:PROCESSOR_ARCHITEW6432 -eq 'ARM64') { $arch = 'arm64' }
  48. Step 'Finding the latest Node.js LTS on nodejs.org...'
  49. # Saved first: Windows PowerShell passes a JSON list down a pipe as one item.
  50. $releases = Invoke-RestMethod 'https://nodejs.org/dist/index.json'
  51. $version = ($releases | Where-Object { $_.lts } | Select-Object -First 1).version
  52. $name = "node-$version-$arch.msi"
  53. $msi = Join-Path $env:TEMP $name
  54. Step "Downloading Node.js $version ($arch)..."
  55. Invoke-WebRequest "https://nodejs.org/dist/$version/$name" -OutFile $msi -UseBasicParsing
  56. if ((Get-AuthenticodeSignature $msi).Status -ne 'Valid') { throw "The Node.js installer isn't signed as expected, so it wasn't run." }
  57. Step 'Installing Node.js. Windows will ask for permission.'
  58. $run = Start-Process msiexec.exe -ArgumentList "/i `"$msi`" /passive /norestart" -Verb RunAs -Wait -PassThru
  59. Remove-Item $msi -ErrorAction SilentlyContinue
  60. if ($run.ExitCode -ne 0 -and $run.ExitCode -ne 3010) { throw "The Node.js installer stopped (code $($run.ExitCode))." }
  61. Update-Path
  62. }
  63. Write-Host 'dotpals installer' -ForegroundColor Magenta
  64. Step 'Checking for Node.js 20 or newer...'
  65. $major = Get-NodeMajor
  66. if ($major -ge 20) {
  67. Ok "Found Node.js $(& node --version)."
  68. } else {
  69. if ($major -gt 0) { Write-Host " Node.js $(& node --version) is too old." } else { Write-Host ' Node.js is not installed.' }
  70. try {
  71. Install-NodeWithWinget
  72. if ((Get-NodeMajor) -lt 20) { Install-NodeFromNodejsOrg }
  73. } catch {
  74. Fail "Couldn't install Node.js. $($_.Exception.Message)"
  75. return
  76. }
  77. if ((Get-NodeMajor) -lt 20) {
  78. Fail 'Node.js 20 or newer still isn''t the one on your PATH. If you use a Node version manager, switch it to 20 or newer, then run this again.'
  79. return
  80. }
  81. Ok "Installed Node.js $(& node --version)."
  82. }
  83. Step 'Installing dotpals (npx --yes dotpals@latest setup)...'
  84. # npx.cmd rather than npx.ps1, which PowerShell's script policy can block.
  85. $npx = Get-Command npx.cmd, npx.exe -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
  86. if (-not $npx) { Fail 'npx is missing. Reinstall Node.js from https://nodejs.org, then run this again.'; return }
  87. & $npx.Source --yes dotpals@latest setup
  88. if ($LASTEXITCODE -ne 0) { Fail "dotpals setup didn't finish (exit code $LASTEXITCODE)."; return }
  89. $global:LASTEXITCODE = 0
  90. Write-Host ''
  91. Write-Host 'dotpals is installed.' -ForegroundColor Green
  92. }
  93. Install-Dotpals
site/install.sh · Bundled script · 88 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # dotpals installer for macOS and Linux.
  3. #
  4. # curl -fsSL https://dotpals.vercel.app/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 4 on GitHub
  5. #
  6. # If Node.js 20 or newer isn't installed, on a Mac it installs it (with Homebrew, or
  7. # the official installer from nodejs.org); on Linux it says how. Then it runs
  8. # `npx --yes dotpals@latest setup`. It only downloads from nodejs.org and npm.
  9. set -euo pipefail
  10. HELP='https://dotpals.vercel.app/guide/troubleshooting.html#installer'
  11. step() { printf '\n\033[36m→\033[0m %s\n' "$*"; }
  12. ok() { printf ' \033[32m✓\033[0m %s\n' "$*"; }
  13. fail() { printf '\n\033[31m✗\033[0m %s\n What to do next: %s\n' "$*" "$HELP" >&2; exit 1; }
  14. # Node's major version, or 0 when there's none.
  15. node_major() {
  16. local v
  17. v=$(node --version 2>/dev/null) || { echo 0; return; }
  18. v=${v#v}
  19. echo "${v%%.*}"
  20. }
  21. # The newest Node.js LTS on nodejs.org, for example v24.11.1.
  22. latest_lts() {
  23. local index
  24. index=$(curl -fsSL https://nodejs.org/dist/index.json) || return 1
  25. awk -F'"' '/"lts":"/ && /"osx-x64-pkg"/ { print $4; exit }' <<<"$index"
  26. }
  27. install_node_mac() {
  28. if command -v brew >/dev/null 2>&1; then
  29. step 'Installing Node.js with Homebrew...'
  30. if brew list node >/dev/null 2>&1; then brew upgrade node || true; else brew install node || fail "Homebrew couldn't install Node.js."; fi
  31. else
  32. step 'Finding the latest Node.js LTS on nodejs.org...'
  33. local version
  34. version=$(latest_lts) || fail "Couldn't reach nodejs.org. Check your internet connection and try again."
  35. [ -n "$version" ] || fail "Couldn't find the latest Node.js on nodejs.org."
  36. tmp=$(mktemp -d)
  37. trap "rm -rf '$tmp'" EXIT
  38. step "Downloading Node.js $version..."
  39. curl -fL --progress-bar -o "$tmp/node.pkg" "https://nodejs.org/dist/$version/node-$version.pkg" \
  40. || fail "Couldn't download Node.js from nodejs.org."
  41. # Apple checks the installer is signed and notarized before we run it.
  42. pkgutil --check-signature "$tmp/node.pkg" >/dev/null || fail "The Node.js installer isn't signed as expected, so it wasn't run."
  43. step 'Installing Node.js. Your Mac will ask for your password (the one you log in with).'
  44. echo ' Nothing shows while you type it; press Enter when done.'
  45. sudo installer -pkg "$tmp/node.pkg" -target / || fail "Node.js didn't install."
  46. export PATH="/usr/local/bin:$PATH"
  47. fi
  48. hash -r
  49. }
  50. main() {
  51. printf '\033[1mdotpals installer\033[0m\n'
  52. step 'Checking for Node.js 20 or newer...'
  53. local major
  54. major=$(node_major)
  55. if [ "$major" -ge 20 ]; then
  56. ok "Found Node.js $(node --version)."
  57. else
  58. if [ "$major" -gt 0 ]; then echo " Node.js $(node --version) is too old."; else echo ' Node.js is not installed.'; fi
  59. if [ "$(uname -s)" != Darwin ]; then
  60. # Linux has too many ways to install Node to guess one; nodejs.org shows the commands for yours.
  61. fail "dotpals needs Node.js 20 or newer. Install it with the commands for your system at
  62. https://nodejs.org/en/download (nvm works everywhere), then run this again."
  63. fi
  64. install_node_mac
  65. major=$(node_major)
  66. [ "$major" -ge 20 ] || fail "Node.js 20 or newer still isn't the one on your PATH (found: $(node --version 2>/dev/null || echo none)).
  67. If you use a Node version manager, switch it to 20 or newer, then run this again."
  68. ok "Installed Node.js $(node --version)."
  69. fi
  70. step 'Installing dotpals (npx --yes dotpals@latest setup)...'
  71. # Piped into bash, our input is this script: give setup the terminal so it can ask its questions.
  72. if (exec </dev/tty) 2>/dev/null; then
  73. npx --yes dotpals@latest setup </dev/tty || fail "dotpals setup didn't finish."
  74. else
  75. npx --yes dotpals@latest setup || fail "dotpals setup didn't finish."
  76. fi
  77. printf '\n\033[32mdotpals is installed.\033[0m\n'
  78. }
  79. # Called on the last line, so nothing runs if the download stops halfway.
  80. main "$@"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.