dotpals Docs

Set up

Configuration

Most settings are on the dashboard's Settings and Agents pages. They're saved in one small JSON file that you can also edit by hand, and a few environment variables cover the rest.

config.json

Settings live in ~/.dotpals/config.json and are shared by the pal, the notch, the dashboard and the bridge. Changes made on the dashboard (or the tray) apply at once. If you edit the file by hand, restart dotpals to pick them up.

{
  "character": "custom",
  "sounds": true,
  "notifications": true,
  "history": true,
  "historyDays": 14,
  "approvals": true,
  "approvalWait": 30,
  "agents": { "cursor": false },
  "custom": { "name": "Pip", "shape": "bean", "eyes": "googly", "top": "crown", "color": "#16c6ae", "fur": true }
}

Only the keys below are kept, and only with valid values. Anything else is ignored, and dropped the next time dotpals saves the file. A key you leave out uses its default.

Keys

KeyDefaultValues
character"blu"The first pal: blu, hop, sunny, lovi, muse, grok, nova, byte, or custom for your own. More sessions get the next characters in turn.
soundstruePlay sounds.
notificationstrueShow desktop notifications (desktop app only).
historytrueKeep activity in ~/.dotpals/history.json, so it survives restarts.
historyDays7How many days of history to keep: a whole number from 1 to 90. At most 5000 entries are kept.
codextrueFollow Codex's session logs. The same switch as agents.codex.
approvalsfalseApprove from the pal: answer Claude Code's permission prompts from the pal or the notch.
approvalWait30Seconds to wait for your answer before Claude asks in the terminal: a whole number from 10 to 120. The dashboard offers 15, 30, 60 and 120.
shareRecapfalseShare with your agents: tell each Claude Code session what your other agents did in the same project.
conflictGuard"ask"Two agents, one file, when an agent is about to change a file another active session just changed: "ask" (Claude Code asks you first), "tell" (Claude Code's edit is stopped and Claude is told to re-read the file) or "off" (no pause and no alerts). Other agents only get the alert.
conflictMinutes10How recent the other session's change must be to count: a whole number of minutes from 1 to 60. The dashboard offers 5, 10, 15 and 30.
fixLooptrueMake agents fix failing tests: tell Claude Code when a test run fails, and send it back (at most twice per request) if it tries to finish, commit or push while the tests fail or weren't run after its last change. Tests changed to pass are caught too. Claude Code only.
agents{}Turn integrations off: { "cursor": false }. Ids: claude, codex, cursor, gemini, opencode, copilot, generic (anything posting to /event). Every integration is on unless it's set to false.
customnullYour own pal: { name, shape, eyes, top, color, fur }, as made in Settings → Make your own pal. See the options.
blu{ "see": true, "hands": true, "click": false, "music": "youtube", "mode": "both", "hearing": "quick", "conversation": true }Talk to Blu. see: take a screenshot when you press Talk's keys, for questions about the screen. hands: let Blu do things on your computer (music, volume, apps, windows). click: let it click, type and press keys too. music: where “play …” plays, "youtube", "youtubemusic", "spotify" or "applemusic" (macOS). mode: what Blu is for, "developer" (Coding), "everyday" or "both". hearing: "quick", "better" or "best". conversation: keep listening after Blu answers.
brain{ "choice": "auto", "models": {}, "polish": "auto", "dictionary": [] }Blu's brain. choice: "auto" or one of ollama, anthropic, openai, google, openrouter, claude, codex, gemini, cursor. models: a model per brain, where you want another than the usual, such as { "ollama": "qwen3" }. polish: clean up dictation, "auto", "always" or "off". dictionary: your words (at most 100), such as "dotpals" or "dot pals → dotpals".
brainKeys{}API keys for Blu's brain: anthropic, openai, google, openrouter, and spotify (your Spotify app's client id:client secret, to open the exact track). Set them in Settings → Blu. Like the TypeSafe key, they're never sent back to a page: GET /api/config shows each one's last 4 characters only.
talkShortcut, circleShortcut, dictateShortcutnoneYour own keys for Talk, circle and ask, and Dictate, as Electron writes them ("CommandOrControl+Alt+T"): one to three of Ctrl, Alt, Shift, Command or Super, then a letter, a digit, F1 to F24 or Space. "" goes back to the usual one (Ctrl+Shift+Space, Ctrl+Alt+C and Ctrl+Alt+D). Set in Settings → Blu → Shortcuts; the desktop app picks up a change at once.
checker{ "mode": "off" }Double-check unclear test results: { mode, localUrl, layaManaged, jevKey }. mode is "off", "local" (Laya on this computer) or "cloud" (TypeSafe Jev). localUrl is Laya's address, default http://127.0.0.1:8000; it must be on this computer (127.0.0.1, localhost or [::1]). layaManaged is true once Set up Laya (or dotpals laya) has installed Laya: dotpals then starts it whenever mode is "local", on the port in localUrl. jevKey is your TypeSafe API key for cloud mode.

The bridge sends the full settings to every open view (GET /api/config returns them too), with agents filled in for every id. The one exception is the API key: it's never sent back. Instead, checker says keySet, keyLast4 (its last 4 characters) and keyFrom ("settings" or "env"). It also carries laya, the status of the Laya dotpals set up: { installed, running, phase, message, line, error, port, log }, where phase is idle, python, venv, install, starting, ready or error.

Laya's folder

Set up Laya keeps everything in ~/.dotpals/laya (or <DOTPALS_HOME>/laya): .venv (a Python environment with Laya and PyTorch), hf (its model), server.log (what it prints, cut back past 5 MB) and server.pid. Remove Laya or dotpals laya --remove deletes the folder. dotpals runs it with LAYA_HOST=127.0.0.1, LAYA_PORT from localUrl and LAYA_MODELS=english, and ignores any other LAYA_* variables you have set.

The TypeSafe API key

Enter it in Settings → Double-check unclear test results → Cloud (Jev): paste it into the TypeSafe API key field and click Save. The page then shows “Saved ••••1234”. Saving with the field empty keeps the saved key; Remove key deletes it. You can also set TYPESAFE_API_KEY in the environment the bridge runs in; a key saved on the Settings page wins over it.

The key is stored in config.json, which dotpals writes readable by you only (mode 600) on macOS and Linux. On Windows the file keeps your user folder's permissions. The key is only ever sent to TypeSafe, by its official SDK (@typesafe-ai/sdk, installed by dotpals setup as an optional package); it isn't logged, shown, or stored with your activity.

Environment variables

Environment variables win over config.json. Set them where the process that reads them runs: bridge variables for the desktop app (or dotpals bridge), and hook variables in your agent's environment, since that's where the hook command runs.

For the bridge and the app

VariableEffect
DOTPALS_HOMEWhere dotpals keeps its settings, history, limits and installed copy. Default: ~/.dotpals.
DOTPALS_HISTORY=0Don't keep history on disk, whatever the setting says.
DOTPALS_CODEX=0Don't follow Codex's logs, whatever the setting says.
DOTPALS_CLAUDE_LOGS=0Don't follow Claude Code transcripts. Sessions then show up only through the plugin's hooks.
DOTPALS_CODEX_DIRThe Codex sessions folder to follow. Default: ~/.codex/sessions, or $CODEX_HOME/sessions when Codex's CODEX_HOME is set.
DOTPALS_CURSOR_DIRCursor's config folder, for Connect. Default: ~/.cursor.
DOTPALS_GEMINI_DIRGemini CLI's config folder. Default: ~/.gemini.
DOTPALS_OPENCODE_DIROpenCode's config folder. Default: $XDG_CONFIG_HOME/opencode, or ~/.config/opencode.
DOTPALS_COPILOT_DIRGitHub Copilot CLI's folder. Default: $COPILOT_HOME, or ~/.copilot.
DOTPALS_PORTThe port the desktop app and the dotpals command use. Falls back to PORT, then 5175.
PORTThe port a bridge started on its own uses (dotpals bridge, dotpals-bridge, node bridge/server.js). Default: 5175.
DOTPALS_ELECTRONThe Electron executable to run the desktop app with, instead of the one dotpals installed.
TYPESAFE_API_KEYYour TypeSafe API key, for double-checking unclear test results in cloud mode, if you'd rather not save it on the Settings page. A saved key wins.

For the hooks

VariableEffect
DOTPALS_URLWhere the hook command (and the OpenCode plugin) sends events. Default: http://127.0.0.1:5175/hook. Setting it also stops hooks from starting the pal.
DOTPALS_AUTOSTART=0Don't start the pal when a Claude Code session starts or a prompt is sent and dotpals isn't running.
DOTPALS_FLOAT=0When the hooks start dotpals, start only the bridge, not the desktop pal.
DOTPALS_BRIDGEThe bridge address the Share with your agents, Two agents, one file and fix failing tests hooks ask, and dotpals mcp reads. Default: http://127.0.0.1:5175.
DOTPALS_DEBUGSet to anything to have that hook print its errors (it's silent otherwise).

Changing the port

dotpals uses port 5175 everywhere by default. To use another one, every part has to agree:

  1. Set DOTPALS_PORT for the desktop app and the dotpals command, or PORT for a bridge you run on its own.
  2. Set DOTPALS_URL=http://127.0.0.1:<port>/hook in the environment of Claude Code, and of any agent you've connected (for OpenCode, the environment OpenCode runs in). This also turns off auto-start. Also set DOTPALS_BRIDGE=http://127.0.0.1:<port> for Claude Code, so fix failing tests, Two agents, one file and Share with your agents find the bridge, and for dotpals mcp in your assistants' MCP settings.
  3. Point your own agents' POST /event at the new port. The dashboard's Any agent card shows the right address.

If something else is using 5175, see Port 5175 is in use.

Where files live

Everything dotpals writes for itself is in ~/.dotpals (or DOTPALS_HOME):

PathWhat it is
config.jsonYour settings (above).
handoff/Hand-off notes, one Markdown file per hand-off. Delete them any time.
history.jsonRecent activity: the last historyDays days, at most 5000 entries. Plain JSON.
claude-limits.jsonClaude Code's usage limits, model name and context-window sizes, saved by the status line. Nothing from your conversations.
statusline.jsonThe status line you had before dotpals statusline, so it keeps working and can be put back.
app/The installed copy of dotpals. Hook commands in other agents' configs point here.
node_modules/The desktop runtime (Electron, about 100 MB).
apps.jsonYour apps, with their sign-ins (tokens included). Readable by you only on macOS and Linux, and never sent to a page. Remove an app in Settings → Apps.
shots/Screenshots for Blu (the newest 20), taken when you press Talk's keys or circle and ask. Delete them any time.
shortcuts.jsonThe shortcuts the desktop app registered (GET /api/shortcuts).
tasks/, tasks.jsonTalk's tasks: one Markdown file per task sent to Claude Code, and the last 30 tasks with their verdicts.
blu/, brain/Where work in your apps runs, and short-lived files for Blu's brain, deleted after each answer.

Also:

  • Window position, size, small mode and notch mode are kept by the desktop app in window.json in its user-data folder: %APPDATA%\dotpals on Windows, ~/Library/Application Support/dotpals on macOS, ~/.config/dotpals on Linux. dictate.log (what Dictate and Blu's hands did) and Blu's downloaded speech models are kept there too.
  • Other tools' files that dotpals can change, each only when you ask, with the original kept as <file>.dotpals-backup: ~/.claude/settings.json (dotpals statusline), ~/.cursor/hooks.json, ~/.gemini/settings.json, ~/.config/opencode/plugins/dotpals.js and ~/.copilot/hooks/dotpals.json (Connect).
  • The Claude Code plugin is installed and managed by Claude Code.
  • The pal page, in the desktop app or a browser, remembers the sound toggle, your first pal and the Tools filter in its local storage.

To remove everything, see Uninstalling dotpals.

Edit this page on GitHub