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
| Key | Default | Values |
|---|---|---|
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. |
sounds | true | Play sounds. |
notifications | true | Show desktop notifications (desktop app only). |
history | true | Keep activity in ~/.dotpals/history.json, so it survives restarts. |
historyDays | 7 | How many days of history to keep: a whole number from 1 to 90. At most 5000 entries are kept. |
codex | true | Follow Codex's session logs. The same switch as agents.codex. |
approvals | false | Approve from the pal: answer Claude Code's permission prompts from the pal or the notch. |
approvalWait | 30 | Seconds 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. |
shareRecap | false | Share 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. |
conflictMinutes | 10 | How 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. |
fixLoop | true | Make 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. |
custom | null | Your 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, dictateShortcut | none | Your 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
| Variable | Effect |
|---|---|
DOTPALS_HOME | Where dotpals keeps its settings, history, limits and installed copy. Default: ~/.dotpals. |
DOTPALS_HISTORY=0 | Don't keep history on disk, whatever the setting says. |
DOTPALS_CODEX=0 | Don't follow Codex's logs, whatever the setting says. |
DOTPALS_CLAUDE_LOGS=0 | Don't follow Claude Code transcripts. Sessions then show up only through the plugin's hooks. |
DOTPALS_CODEX_DIR | The Codex sessions folder to follow. Default: ~/.codex/sessions, or $CODEX_HOME/sessions when Codex's CODEX_HOME is set. |
DOTPALS_CURSOR_DIR | Cursor's config folder, for Connect. Default: ~/.cursor. |
DOTPALS_GEMINI_DIR | Gemini CLI's config folder. Default: ~/.gemini. |
DOTPALS_OPENCODE_DIR | OpenCode's config folder. Default: $XDG_CONFIG_HOME/opencode, or ~/.config/opencode. |
DOTPALS_COPILOT_DIR | GitHub Copilot CLI's folder. Default: $COPILOT_HOME, or ~/.copilot. |
DOTPALS_PORT | The port the desktop app and the dotpals command use. Falls back to PORT, then 5175. |
PORT | The port a bridge started on its own uses (dotpals bridge, dotpals-bridge, node bridge/server.js). Default: 5175. |
DOTPALS_ELECTRON | The Electron executable to run the desktop app with, instead of the one dotpals installed. |
TYPESAFE_API_KEY | Your 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
| Variable | Effect |
|---|---|
DOTPALS_URL | Where 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=0 | Don't start the pal when a Claude Code session starts or a prompt is sent and dotpals isn't running. |
DOTPALS_FLOAT=0 | When the hooks start dotpals, start only the bridge, not the desktop pal. |
DOTPALS_BRIDGE | The 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_DEBUG | Set 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:
- Set
DOTPALS_PORTfor the desktop app and thedotpalscommand, orPORTfor a bridge you run on its own. - Set
DOTPALS_URL=http://127.0.0.1:<port>/hookin 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 setDOTPALS_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 fordotpals mcpin your assistants' MCP settings. - Point your own agents'
POST /eventat 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):
| Path | What it is |
|---|---|
config.json | Your settings (above). |
handoff/ | Hand-off notes, one Markdown file per hand-off. Delete them any time. |
history.json | Recent activity: the last historyDays days, at most 5000 entries. Plain JSON. |
claude-limits.json | Claude Code's usage limits, model name and context-window sizes, saved by the status line. Nothing from your conversations. |
statusline.json | The 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.json | Your 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.json | The shortcuts the desktop app registered (GET /api/shortcuts). |
tasks/, tasks.json | Talk'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.jsonin its user-data folder:%APPDATA%\dotpalson Windows,~/Library/Application Support/dotpalson macOS,~/.config/dotpalson 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.jsand~/.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.