Set up

Command line

The dotpals command installs dotpals, starts the pal and the dashboard, and sets up the notch and Claude Code's usage limits.

Running it

Setup installs dotpals in ~/.dotpals/app but doesn't add a dotpals command to your PATH. Run commands with npx, or with Node from the installed copy:

npx --allow-git=all github:rikinshah787/dotpals <command>
node ~/.dotpals/app/bin/dotpals.js <command>

These docs write dotpals <command> for short. Run dotpals with no command (or an unknown one) to print the version and this list:

Command	What it does
`setup`	Install, connect Claude Code and Codex, and start the pal.
`start`	Open the floating pal.
`dashboard`	Open the dashboard.
`status`	What's running and connected.
`notch`	Choose when the notch shows at the top of the screen.
`statusline`	Let Claude Code share its usage limits with dotpals.
`laya`	Set up Laya, the free checker for unclear test results that runs on this computer.
`bridge`	Run only the bridge, with no window.

setup

dotpals setup [--no-claude] [--no-login] [--no-start]

Installs or updates dotpals and starts it. Run it again any time to update. In order, it:

checks that Node is version 20 or newer, and stops if it isn't,
copies dotpals to ~/.dotpals/app (npx runs from a temporary folder),
downloads Electron, the desktop runtime (about 100 MB), into ~/.dotpals if it isn't there yet,
creates ~/.dotpals/config.json if needed,
adds the Claude Code plugin with claude plugin marketplace add rikinshah787/dotpals and claude plugin install dotpals@dotpals, if the claude command is found (restart Claude Code to load it),
reports whether Codex is installed (~/.codex). Its sessions show up automatically,
starts the pal, sets it to open when you log in, and opens the dashboard. If the pal is already running, it opens the dashboard in your browser. If Electron couldn't be installed, it starts the bridge in the background and opens the dashboard in your browser.

Flag	Effect
`--no-claude`	Skip the Claude Code plugin.
`--no-login`	Don't turn on Open when I log in.
`--no-start`	Don't start the pal or open the dashboard.

start

dotpals start

Opens the floating pal (the desktop app), which starts the bridge if it isn't running. If the pal is already running, it's brought back on screen. If the desktop runtime isn't installed, it tells you to run setup and exits with code 1.

dashboard

dotpals dashboard

Opens the dashboard in the desktop app's own window, starting the app if needed. Without the desktop runtime, it opens http://127.0.0.1:5175/dashboard in your browser if the bridge is running, or tells you to start dotpals first.

status

dotpals status

Asks the running bridge what's going on, for example:

dotpals 0.7.0 running on port 5175
  Claude Code        last event 2m ago
  Codex              last event 0m ago
  Cursor             connected, last event 14m ago
  Gemini CLI         found, not connected (dashboard → Agents)
  OpenCode           not found
  GitHub Copilot CLI not found
  Any agent          last event not yet
  History      /home/you/.dotpals/history.json (812 entries)
  Dashboard    http://127.0.0.1:5175/dashboard

An integration you've switched off reads off. The entry count is what the bridge holds right now. If dotpals isn't running, it says so and exits with code 1.

notch

dotpals notch          # always show the notch
dotpals notch --auto   # show it only while the pal is hidden (the default)
dotpals notch --off    # never show it

Sets when the notch appears at the top of the screen, and starts the desktop app if it isn't running. The same choice is in the tray menu under Notch at the top of the screen. It's saved with the app's window settings (see where files live). Needs the desktop runtime.

statusline

dotpals statusline         # share Claude Code's usage limits with dotpals
dotpals statusline --off   # undo it

Claude Code gives its 5-hour and weekly usage limits only to a status line command, so this sets dotpals' status line in ~/.claude/settings.json:

It backs up your settings to ~/.claude/settings.json.dotpals-backup first.
If you already had a status line, it's saved in ~/.dotpals/statusline.json, and dotpals runs it and shows its output, so nothing changes on your screen. Otherwise dotpals shows a short line of its own, such as ● Opus · 5h 42% · week 18% · context 31%.
Each time Claude Code refreshes the status line, the limits (and each session's context window size) are saved to ~/.dotpals/claude-limits.json for the notch.
Running it twice is harmless. If settings.json can't be read, nothing is changed.

--off puts your previous status line back (or removes dotpals' one) and deletes statusline.json. If dotpals isn't your status line, it changes nothing.

laya

dotpals laya            # set up Laya and check it answers
dotpals laya --remove   # stop it and delete it

The same as Set up Laya on the Settings page (Double-check unclear test results → Local), with its progress in the terminal. It finds Python 3.10 or newer (py -3 on Windows, then python3, then python), makes a Python environment in ~/.dotpals/laya, installs laya[serve] there with pip, starts laya-serve once on 127.0.0.1 to download the model and check that it answers, and turns the checker on Local. The first run downloads a few GB (PyTorch and the model) and can take a while; running it again only checks that Laya starts.

When the bridge is running, it does the setup (so there's only ever one Laya) and this command shows its progress. Otherwise this command stops Laya again at the end, and dotpals starts it whenever the checker is on Local.
No Python? It says so: install Python 3.10 or newer from python.org (on Windows, tick Add python.exe to PATH in the installer), then run it again.
--remove stops Laya, deletes ~/.dotpals/laya (its Python environment and its model) and turns the checker off if it was on Local.

bridge

dotpals bridge

Runs only the bridge, in this terminal, with no window. Useful on a machine without a desktop, or to use dotpals in a browser. It prints:

dotpals bridge → http://localhost:5175
dashboard      → http://localhost:5175/dashboard
hook endpoint  → http://localhost:5175/hook

Stop it with Ctrl+C. To use another port, set PORT (see Changing the port).

Other commands

The package has two more commands, and the Claude Code plugin adds one:

Command	What it does
`dotpals-bridge`	The bridge on its own, like `node bridge/server.js`. If a bridge is already running on the port, it says so and exits.
`dotpals-float`	Opens the floating pal, like `node desktop/launch.js`. `--install` downloads Electron into `~/.dotpals` first if it's missing.
`/dotpals:pals`	In Claude Code: opens the pal, offering to download the desktop runtime the first time. See Only the Claude Code plugin.

The desktop app also accepts these flags, which the commands above pass for you: --dashboard, --open-at-login, --notch, --notch-auto and --no-notch. Launching the app while it's running hands the flags to the running copy.

From a checkout

If you've cloned the repository:

npm install           # dev only: Electron for the desktop window
npm test              # node --test, no dependencies needed
npm run float         # the desktop pal
npm run bridge        # only the bridge
npm run dashboard     # the dashboard
npm run setup         # the one-command setup, from this checkout
npm run dev           # the web component playground on http://localhost:5173
npm run example:agent # an example Server-Sent Events harness on http://localhost:5174