Skip to content

The desktop app

Generated from PersonalClaw v0.3.9, the release this site publishes.

PersonalClaw’s desktop shell is a thin Electron wrapper around the same gateway and dashboard you get in a browser. It exists for the things a browser tab cannot do: a menu-bar presence, native permissions, and a global push-to-talk shortcut that works while another app has focus.

Everything the shell adds is a capability, granted individually and visible in Settings → Security → Desktop capabilities. In a browser tab that panel says “desktop app not connected” and none of this applies.

The shell puts an icon in the macOS menu bar and keeps it there while PersonalClaw is running. Its menu is live, refreshed every few seconds from the local gateway. Its first line says the state in words: Nothing running, Working: 2 running, Needs you: 1 waiting on you, Something stopped, Listening, Not connected to the gateway, or PersonalClaw is restarting while a restart you asked for is under way. The tooltip says the same.

  • Waiting on you — everything that waits on your answer, one row each, before what is running and in the order every surface lists them (GET /api/waiting): approvals, an agent’s questions, a loop’s question, a workflow’s gate, an automation’s parked action, a browser grant, a plan to review and a control-bridge confirmation. Each row says what kind it is and what it asks, in the app’s own words, and opens where you answer it. The first 8 are listed, and one row for the rest opens Needs you, which lists each with its answer. With nothing waiting, the row says so and still opens Needs you, so it is a way in rather than a row that greys out the moment you catch up.
  • Running — everything running now, the same list Home’s Your agents today shows (GET /api/running): a chat’s turn, a helper, a loop, a workflow run, an automation’s fire and a webhook’s turn, each once. Each entry says the work’s name, its phase, what it is doing and when that last changed, and opens the work where it runs (Home for work no page opens). A blocked entry (queued for a slot, retrying, waiting on a busy model) says so, and the row counts how many are; an entry that waits on you says how much does. The first 8 are listed, and the rest open on Home. With nothing running it says Nothing running; when the list cannot be read it says so; and while the gateway cannot be reached it keeps the last entries it read, as Last known.
  • Just finished — the last endings, each saying how it ended (done, or stopped with its reason) and when, and work a gateway restart cut off, said as Interrupted until it runs or ends again, or for ten minutes.
  • Quick Capture Note — opens the Inbox with its note composer open, the same one the Inbox header’s Capture a note opens. What you write is saved as your own Inbox item, up to 4,000 characters; if the save fails, your text stays in the composer.
  • Show Buddy (see The buddy), Open PersonalClaw, Open at Login, and Quit PersonalClaw.

When the count beside the icon and the ”● Listening” capture indicator want the same space, listening always wins — a live microphone is never hidden behind a badge.

With Show Buddy on, and the menu-bar icon among its surfaces, the icon is the buddy’s still orb for the state instead of the claw: idle, working, needs you, error, listening or offline. Each keeps its badge and its dots’ density, so it reads in a one-colour menu bar, in high contrast and with no animation, and the first line of the menu and the tooltip say the state in words. No count sits beside it. Listening always wins the icon, and an announced restart shows working, never offline. On macOS, the dock icon shows the needs-you orb while something waits on you, and goes back to the app icon when nothing does; Linux has no dock icon to change. On Linux the orb is drawn in one ink, your light or dark appearance’s own, which holds 3:1 against the bar at 18 px; macOS draws its menu-bar images in the bar’s ink itself, Increase Contrast included.

If the gateway cannot be reached the menu says “not connected” rather than showing zeroes, because a zero looks like good news.

Closing the window hides it; the menu-bar item brings it back, and PersonalClaw keeps running. If the menu-bar item could not be created — a missing icon, or a platform without one — the shell notices and closes the window for real instead, so you can never end up with a running app you have no way to reach.

Off by default. There are two places to turn it on, and they are the same switch: the menu bar’s Open at Login, and Settings → Security → Desktop capabilities → Open at login. Flip either and the other follows — there is one registration, not one per surface.

It registers this app with macOS Login Items — the same list in System Settings → General → Login Items, where you can also remove it without launching PersonalClaw. It needs no administrator password, writes no launch agent of its own, and turning it on twice cannot leave two entries behind.

macOS owns this setting, so PersonalClaw keeps no copy of it. Both surfaces read the registration from the OS every time they draw, which is why removing it in System Settings shows up here rather than leaving a switch stuck on. If macOS declines the change, the switch says so and stays where the OS actually left it.

In a browser tab there is no switch: registering a login item needs the desktop app, and a toggle that could not do anything would be worse than an honest absence.

How the app signs in to the gateway it starts

Section titled “How the app signs in to the gateway it starts”

The gateway the app starts asks every request for a sign-in, exactly as a gateway started any other way does: token sign-in is on, and it listens on this computer only. The app does not turn that off, and it does not pass on the variables that would (PERSONALCLAW_AUTH_MODE, PERSONALCLAW_BYPASS_LOCAL_NETWORKS, PERSONALCLAW_BIND_HOST), even when it is started from a terminal that sets them. The app’s own gateway always listens on this computer only, whatever bind host the home stores; to reach PersonalClaw from another device, run the gateway yourself (remote access).

Each time the gateway starts it hands the app a sign-in made for that start, on a pipe only the app reads, and the app signs its windows in with it:

  • It is kept in memory only. The windows carry it as the gateway’s session cookie, which the app holds for as long as it runs and never writes to disk; the app’s own requests, such as the menu bar’s counts, carry it in a header. It is never put in an address, so no window’s history holds it, and the app never writes it to its log.
  • Every window is signed in. The main window, a new tab, a page a link opens in its own window, and the menu bar’s and notifications’ links into the dashboard all share it.
  • Quitting signs it out. While the app runs, Settings → Devices & Access → Devices lists it as “PersonalClaw desktop app”. Quitting ends that sign-in, and the next launch makes a new one.
  • A restart signs the windows in again. When the gateway restarts in place, it comes back on a new port with a new sign-in. The app follows it there: each window on the dashboard or an app’s own page reloads it, signed in, the main window goes to the dashboard, any other window closes, and the sign-in from before the restart is ended.
  • A gateway that goes away gets nothing. While the app has lost its gateway, nothing the windows send reaches it, and their sign-in is out of the app’s cookies. The windows stay where they are and come back by themselves once the app has made sure the same gateway is back, and after a restart in place or the app’s own update. A gateway this app didn’t start that is stopped and started again reads as gone: use it again from the This computer row.

So everything else on this computer meets the same door a browser does. Another program cannot list or answer your approvals without signing in, an app you installed reaches only the routes its permissions declare, and the credential an agent CLI’s tools hold opens only the operations it exists for.

If the app is signed out from another device (Settings → Devices & Access → Devices), or its sign-in runs out (auth.session_ttl, 30 days by default; or 30 days, at a gateway this app didn’t start), the window says so, and the Gateways window’s This computer row says the app is signed out, with Sign In Again. The row says the same when a gateway can’t sign the app’s windows in after three tries; where Sign In Again can’t help, it reads Can’t sign in, with what to do. With a gateway older than this app, quit PersonalClaw and open it again instead.

A gateway from 0.3.7 on needs the app from 0.3.7 on. Such a gateway asks each browser’s sign-in for more than its cookie, and only the app from 0.3.7 on signs its windows in that way. An older app’s window on it says so and names the releases page: update the app there.

The app starts its own gateway when it opens. Only one gateway serves a PersonalClaw home, so if one already serves the app’s home (one you started in a terminal, or a service), that start is refused, and the app looks for the running one. It offers it in the chooser as Use the Gateway Already Running, and signs in to it only when you press that. Tick Use it automatically next time, and the next time the app’s own start is refused, it uses that gateway without asking; that box is off until you tick it, and Ask Each Time on the Gateways window’s This computer row turns it off again. Either way:

  • It is found the way personalclaw token finds it. The app reads where the home’s gateway said it listens, then asks it, on 127.0.0.1 and with no credential, which home it serves. It goes on only once that gateway proves it holds the home’s local secret. Another home’s gateway, a program that is not one, or an older gateway that cannot prove it, gets nothing more: the Gateway → Gateways… window says which it was.
  • It uses one at its own version or newer. A gateway it found that runs an older version than the app, or a build the app can’t use, is not signed in to: the Gateways window’s This computer row says which, and offers Try Again once you have updated the gateway or installed it again. For an older one the row and the chooser offer Update the Gateway first: the app asks the gateway to update itself to the release it resolves, this app’s version or newer, after a confirm that says what its restart interrupts, waits until it is back on this app’s version or newer, and then uses it. A gateway that can’t update that way (a container, another app’s built-in gateway, a checkout on the Developer channel, or one pinned to another release) says why on the row instead.
  • It signs in as the CLI does, with the home’s local secret, for 30 days, as long as the app’s own sign-in lasts by default. The sign-in is held exactly as that one is: in memory, as the windows’ session cookie, never on disk or in an address. Quitting ends it.
  • The app never stops it or signals it. Quitting PersonalClaw leaves it running. The Gateways window marks it already running, so you can tell it from one the app started.
  • The app follows it. When it restarts (Settings → Restart, or an update), the app finds it again, on a new port if it moved. Until that gateway proves again that it serves this home, the app sends nothing that carries the home’s sign-in or its local secret to the port it was on, so a program that took that port gets none of them. When it stops, the app says so, and the chooser offers to try again, which starts the app’s own gateway, or to add another one.
  • Desktop capabilities work there, since it proved it serves this home: see below.

A window signed in this way is asked to confirm it’s you before it pairs a device or creates a token once its sign-in is more than ten minutes old, as a browser tab is. Quitting PersonalClaw and opening it again signs it in afresh.

When the app’s own gateway starts, no other window opens: Gateway → Gateways… is in the menu when you want it. If the app cannot start its gateway, for any reason, or the one it used stops, the main window says it is not connected, and a small window, Choose a Gateway, opens on its own. It says why (how the gateway exited and the last thing it said, that another gateway serves your home, or that the gateway it used has stopped) and offers:

  • Use the Gateway Already Running, only when this home’s gateway is running and has proved it serves the home (above), with Use it automatically next time;
  • Add a Gateway…, which opens the Gateways window, where you connect to another gateway, on this computer or elsewhere;
  • Try Again, which starts the app’s own gateway again.

The Gateways window’s This computer row says the same, and offers Start a Gateway Here, or Use It for a running gateway the app found. If a gateway serves your home that the app cannot sign in to, the row says why and offers Try Again instead.

If your home was last used by a newer PersonalClaw than the app’s own gateway (an app kept from an older release, say), that gateway is refused the home: an older version could lose what the newer one saved. The chooser and the row name the version that used it and offer Open the Releases Page for the newer app, never Try Again, which would be refused again.

When the app and a pip install share a home, whichever is newer sets the floor. Opening a newer app while your own gateway is stopped moves the home forward, and your older gateway then asks to be updated.

On macOS the window has no title bar of its own: the window controls (close, minimize, zoom) sit in the strip above the sidebar. The sidebar and the page beside it paint the same colours as the web UI, in light and in dark, with no translucent material, so their text keeps its contrast.

A switch between light and dark, from the Theme button at the top right, Settings → Appearance, or macOS while the theme is System, changes the sidebar, the strip above it, the window and its tabs and menus at once, with no need to leave the app and come back. From its second launch on 0.3.8 the app opens in the theme you last used; at the first, the window opens in macOS’s mode and then takes the theme of the dashboard, which opens in the theme it opened in before. When this computer’s gateway is from before 0.3.8, the strip and the window’s tabs and menus change at its next load or when you come back to the app; another gateway from before 0.3.8 changes them just after the click or key.

On Linux the window keeps its plain frameless look, in the same colours.

A personalclaw:// link opens the desktop app on one of its pages, from a browser, another app or Terminal (open "personalclaw://settings" on macOS). The installed app registers the scheme; a development run started from the repository does not take it over.

personalclaw://<page>[/<item>...][?<state>=<value>&...]
  • The page is one of the dashboard’s pages, by the name its address uses: dashboard, chat, projects, library, knowledge, memory, tasks, inbox, automations, triggers, files, artifacts, terminal, capabilities, agents, tools, skills, learning, prompts, workflows, apps, settings, notifications, discover, loop, loops, code, app or mission-control. threads is another name for chat. Names are lower case. The app’s three shell pages, onboarding, companion and the buddy (buddy, its presence and its playground), are not on the list: a link to any of them is refused.
  • Up to four items follow: a thread, a settings panel, an item’s id. Each is letters, digits and . _ : @ ~ -.
  • The state is project, mode, pane, file (a path inside the thread’s folder), on a new thread only prompt, and on a code project’s cockpit only diff, commit and task, each given once. An artifact has a page of its own, so a link names it as one (personalclaw://artifacts/<slug>); an artifact key gets the link refused.

What the dashboard does with the state:

  • prompt is put in the new thread’s composer, and nothing more. It is not sent: you read it, change it if you like, and send it yourself. The address then holds it as the draft, so a reload shows it in the composer again, still unsent. If the app is already showing a new thread, the link opens a fresh one with its prompt in place of the unsent draft.
  • pane opens one of the chat’s panes: activity on a thread, history on a new thread. A pane the thread does not have is left closed. Other pages, apart from a code project’s cockpit (below), do not read pane.
  • file is the file the thread’s file pane opens beside it.
  • project binds a new thread to that project, as the project’s own Chat button does.
  • mode is read by the page it names, as that page’s own address does: Skills opens its Browse or Proposals view (mode=browse, mode=proposals), and the new-loop form opens with Attended on (personalclaw://loop?mode=attended). On a thread it is the task mode: agent, ask, plan or build. A new thread opens in that mode, which reaches the gateway only when you send, as a mode you pick on the pill does. If the app is already showing a new thread in another mode, the link moves it to the link’s mode (Agent, for a link with no mode) and puts its approval back to Normal, as on a new thread the link opens, so a link never leaves an auto-approve you picked for another mode; your draft stays. An existing thread keeps the mode it has, and the address is corrected to it, so a link never changes how a chat runs. The address follows the mode as you change it, so a reload or a copied address opens the chat in the mode it was in.

On a code project’s cockpit (personalclaw://code/<id>) the state is the review you had open, and the cockpit’s own address keeps it as you click, so a reload, Back or a copied address opens the same review:

  • pane is the files rail’s tab: changes, or files, which is also what it shows with none.
  • file, diff or commit is the one thing the center shows: a file open in the editor, a file’s working-copy diff, or a commit’s changes. A file and a diff are paths inside the project’s workspace; a commit is its hash, 7 to 40 lowercase hex characters. The center shows one at a time, so a link that names more than one of the three is refused. A commit’s hash is only read: it opens that commit’s changes and goes nowhere else. A commit the Changes tab lists by a shorter hash, as git abbreviates in some repositories, opens when you click it, and the address then names none of the three. A diff opens in the review pane beside the editor, under the list of the workspace’s uncommitted changes.
  • A cockpit address with no key at all opens the review pane on the first uncommitted change, and the address then names its diff. A review you close stays closed in that window until you open a diff again, so a reload does not bring it back.
  • task opens that task’s detail in the Tasks panel. Opening it only shows it: its steer box starts empty, and nothing is queued or sent. A task that is not in the project’s lists is closed again once they are read and hold a task.

diff, commit and task on any other page get the link refused.

For example:

LinkOpens
personalclaw://threads/new?prompt=draft%20thisa new thread, with the prompt in its composer, unsent
personalclaw://settings/providersSettings, at its providers address
personalclaw://capabilitiesCapabilities
personalclaw://skillsSkills, a tab of Capabilities
personalclaw://memoryMemory, a tab of the Library
personalclaw://automationsAutomations
personalclaw://artifacts/<slug>that artifact
personalclaw://threads/<key>?pane=activity&file=src%2Fapp.pythat thread, with its Activity pane and that file open
personalclaw://code/<id>?pane=changes&diff=src%2Fapp.py&task=<task>that code project, on its Changes tab, with that file’s diff and that task open

A link only opens a page. It never acts. It sends nothing, approves nothing, answers nothing and runs nothing. Any other key in a link, a key that would act included, gets the link refused. So does an unknown page, an encoded /, #, ? or quote inside an item, a fragment, a value that is too long or the wrong shape, a file path outside the thread’s folder, more than one of file, diff and commit, and a prompt with control characters other than tabs and line breaks. A refused link brings the app forward and changes nothing.

A link that arrives while the app is still starting waits until the dashboard has loaded, and only the newest one waits. It is delivered once, and only to the dashboard of the gateway the window shows: never to the loading page, the gateway switcher, the gateway’s sign-in or pairing page, or another site. The app’s log says which page a link opened, or why it was refused, and never repeats the link itself, which can hold a prompt.

The app’s windows show only the dashboard of the gateway you are looking at. A link to another site, a window a page asks for on another site, and a page a server redirects to all open in your default browser instead. Only a web address (http or https) is handed to the browser: a file, another app’s link or a blank page is not opened at all.

Signing in to a remote tool server on the Tools page works the same way. Its sign-in page opens in your browser, the Tools page says it opened there, and the server’s card turns to signed in once you finish. If the app could not open your browser, the page says why and gives you the sign-in link to copy into a browser yourself. On a gateway you paired with (below), the page cannot ask the app to open it, so it offers the link instead, and the link opens in your browser too.

By default the desktop app uses this computer’s gateway: the one it starts and loads, or, when that one doesn’t start, the one already serving your home, once you choose it. Nothing below happens unless you ask for it.

Gateway → Gateways… (⌘⇧G) opens the switcher. It lists every gateway you have paired with, marks the one you are looking at, and lets you add another — a PersonalClaw running on a different machine on your network, or your own gateway reached through the remote access tunnel. Picking a different one reloads the dashboard from that gateway. Nothing is shared between them: see No hub, ever.

On the gateway you want to reach, open Settings → Devices & Access → Devices → Pair a device. It gives you a link that looks like http://claw.local:10000/pair?code=ABCD-2345. Paste that whole link into the switcher.

Paste the link, not just the code, because the address in it was composed by that gateway rather than typed by you — so there is no address to get wrong. The app then shows you exactly which host it is about to open, and which network that host is on, and waits for you to say yes.

You can type a bare address instead (192.168.1.5:10000) if you are reading it off a screen. Same checks, same confirmation, but now the address is only as right as your typing.

What the app refuses, and what it asks you about

Section titled “What the app refuses, and what it asks you about”

The three cases are genuinely different and the app treats them differently:

Where the gateway ishttp://https://
This computer (127.0.0.1, [::1])fine, no prompt — this is the default modefine
Your network or tailnet (10.x, 192.168.x, 172.16–31.x, 100.64–127.x, *.local, *.ts.net)allowed once you confirm, with a plain warning that the traffic is readable by anyone else on that networkallowed once you confirm
Anywhere else (the public internet)refusedallowed once you confirm

A name, localhost included, is never taken as this computer: the app asks first, as it does for an address on your network. A gateway you reach at localhost through a proxy on another port signs in again after each launch, so add it by its 127.0.0.1 address.

Plaintext to a public address is refused rather than warned about. A gateway reached over the internet goes through your own tunnel, which terminates TLS, and the session cookie it sets is Secure — so it would not be sent over http:// anyway. “It does not work” is not a trade-off worth offering you.

A few addresses are refused outright, and they are all the same kind of thing: an IP written as a number or in hex (2130706433, 0x7f000001), an IPv4 address written as IPv6 (::ffff:127.0.0.1), a link-local address (169.254.x — one of which is a cloud metadata service), and any address with a username and password in it. None of these is something you would type on purpose, and each is a known way to make one program disagree with another about which machine an address names.

A name is also checked against what it actually resolves to. If brain.example.com points into your LAN, the app says “your local network” rather than “the public internet”. If it points at more than one kind of network at once, the app will not connect, because it cannot tell you one true thing about where you are going. And a name that resolves to 127.0.0.1 is treated as a network address, never as this computer — the next section is why that distinction is load-bearing.

Desktop capabilities are for this home’s gateway only

Section titled “Desktop capabilities are for this home’s gateway only”

The microphone, the global shortcut, native notifications, the login item and opening a sign-in page in your browser are exposed to the dashboard through a bridge the app attaches to the page. That bridge is only ever attached to the gateway that serves this app’s home: the one the app started, or the one already serving the home once it proved it holds the home’s local secret. Any other gateway gets a plain window: the panel in Settings → Security → Desktop capabilities reads “desktop app not connected”, exactly as it does in a browser tab, push-to-talk does nothing there, and a remote tool server’s sign-in offers its link rather than opening it.

That is not a limitation waiting to be lifted. The bridge is authorised by a secret file in ~/.personalclaw, which proves “I am running as you, on this machine” — a claim only the home’s own gateway can check. So the shortcut and the microphone follow this home’s gateway, and switching to another one leaves them behind.

The switcher shows a status per row, and the statuses mean different things on purpose:

  • Not checked yet — nobody has asked. Not the same as a failure.
  • Not answering / Timed out — the machine is off, asleep, or off the network. The app re-checks on a widening delay a bounded number of times, then stops and waits for you. When it answers again, the dashboard reloads by itself.
  • Signed out — the gateway signed this app out: from Settings → Devices & Access → Devices on another device, with “Sign out all other devices”, or because its sign-in ran out. The window shows the gateway’s own sentence saying why, when, and how to sign back in, and the row carries the same sentence. To pair it again, choose Pair a device in Settings → Devices & Access → Devices on a device that is still signed in, and paste the pairing link into Gateway → Gateways… here.
  • Refused the connection check — the address answered the app’s health check with a refusal. A PersonalClaw gateway never does (the check needs no sign-in), so something in front of it — a proxy asking for a password, say — or something else is answering. The app stops immediately and does not try again: asking again achieves nothing and could trip a lockout.
  • Answered, but not a PersonalClaw gateway — something is at that address, and it is not this.
  • Redirected somewhere else — the address answered by pointing at a third host. The app does not follow it.

Revoking one gateway’s device session breaks that row and nothing else. The others keep working, and switching back to them does not ask you to pair anything.

In ~/.personalclaw/desktop/shell-store.json, readable and writable by your account only. If those permissions are ever loosened — so that another account on the machine could edit it — the app will not silently connect to whatever it finds there: it starts its own gateway and asks you to confirm the address again. If the file is damaged it is left exactly as it is rather than overwritten, so nothing is lost while you look at it.

The file holds addresses and names. It holds no tokens: your session for each gateway is an http-only cookie in the app’s own cookie jar, which is also why pairing happens on the gateway’s own page rather than inside the app.

The desktop app starts its own gateway, so quitting has to stop it in the right order. Quit asks the gateway to shut down and then waits for it to actually exit before the app goes away, rather than sending a signal and disappearing — the difference between a clean stop and a half-finished write. A gateway that will not stop is escalated after a few seconds, and if it still will not, the app says so in its log rather than pretending the quit was clean.

A gateway the app did not start (one already serving your home) is left running: quitting signs the app out of it, and nothing more.

Restart stops the gateway and starts it again in place: it comes back on a new port, and the windows follow it there (see How the app signs in). A restart whose program can no longer be run is refused before anything stops, and the window says so; the gateway keeps running as it is.

Any other time the gateway stops while the app is open (it crashed, something ended it, or a restart could not start it again), the app says so in the chooser and on the Gateways window’s This computer row: PersonalClaw’s gateway stopped, with how it exited and the last thing it said. Try Again (Start a Gateway Here on the row) starts a new gateway, and every window moves to it, signed in, the way it does after a restart; a start that fails says so the same way.

A gateway that cannot start when the app opens is the same news, said as soon as the start fails: PersonalClaw’s gateway did not start, with how it exited and the last thing it said. A gateway that started and never answered, within two minutes, is said the same way. When another gateway serves the app’s home, the chooser offers it (above).

What the desktop app runs, and what needs the installed version

Section titled “What the desktop app runs, and what needs the installed version”

The desktop app runs PersonalClaw’s gateway from one bundled program. It carries the Python packages PersonalClaw is built with, the model SDKs among them, and it starts no other Python program. So everything that runs inside the gateway works: chat, agents and their tools, memory and knowledge, automations, prompts and subagents, documents, sheets, decks and PDFs, the workflow templates and the bundled skills, and the PersonalClaw tools an agent CLI is given. So do the apps whose code runs in the gateway, every model app whose packages the bundle carries (OpenAI and the OpenAI-compatible ones, Anthropic) among them. An app whose server runs on Node runs too, when Node is installed.

What needs a Python program of its own does not run in the desktop app. It is refused before anything of it starts, with one sentence that says what the desktop app can’t run and that the installed version can:

WhatWhere the desktop app says so
An app that runs its own Python server or background worker, an engine in a Python environment of its own, connector-pack parse scripts, or Python packages the bundle does not carryits Store card and details, which offer no Install; the install dialog; Activate. An app like this already installed, in a PersonalClaw folder the installed version also uses, says it on its Library card and details, and never starts, so nothing retries it.
Install engine, for an app whose engine runs in a Python environment of its ownits engine section in Settings → Models & Providers → Providers, when you press it
A command in the Linux sandbox: the agent’s bash tool, a hook or command automation, a scheduled script, an agent CLI’s session, the terminal (Linux only)where it would run: the tool call, the run, the terminal. The command is not run, and it never runs outside the sandbox.
personalclaw doctor’s pip: rowthe row says the desktop app installs no Python packages

To use any of them, install PersonalClaw with uv, as Getting started describes:

Terminal window
uv tool install --python 3.13 personalclaw

The installed version runs all of the above, and it uses the same PersonalClaw folder (~/.personalclaw), so your conversations, settings and installed apps are there. The desktop app installs no Python packages in that folder and leaves the ones the installed version installs for its apps alone. Quit the desktop app before you start it, so the two do not run on one folder at once.

Press the shortcut, speak, press it again. The recording is transcribed by whichever model you bound to the STT use case (Settings → Models & Providers → Models) and the text is inserted into the composer at your cursor — it does not replace or append to what you had already typed.

Dictation needs somewhere to land, so the shortcut is armed wherever a composer is — chat and the goal composer. On a screen with no composer (Settings, say) it does nothing rather than recording into nowhere, which also means the capture indicator is never lit somewhere you cannot see what it is feeding.

With more than one tab open (⌘T), a press goes to the tab you are using; pressed from another app, it goes to the tab you used last. Each tab’s composer records on its own.

The shortcut is configurable in Settings → Speech & Transcription → Hands-free voice. The default is ⌘⇧Space. A shortcut needs at least one modifier: a bare key would be taken away from every other app on your machine, so PersonalClaw refuses to bind one. If another app already owns the chord you pick, the setting says so and keeps your previous shortcut rather than silently failing at the next launch.

The global shortcut toggles capture: one press starts, the next stops. This is a real platform limit rather than a shortcut we took — Electron’s global-shortcut API delivers a press and exposes no key-release event, and reading raw key-up system-wide would mean requesting an accessibility-level input tap, which PersonalClaw does not do.

The practical difference is that you cannot hold the chord down. So that a forgotten toggle cannot leave the microphone open indefinitely, a capture that runs past two minutes is stopped for you, in each tab on its own.

While it is capturing you can always see it

Section titled “While it is capturing you can always see it”

Two indicators are lit while the microphone is live, and both matter:

  1. macOS’s own orange microphone dot in the menu bar. That one is drawn by the system, and PersonalClaw cannot suppress or fake it — which is exactly why it is the one to trust.
  2. PersonalClaw’s menu-bar item changes to ● Listening. This says which app is listening, which the system dot cannot. It is in the menu bar rather than in the page because the shortcut is global: if the window were hidden behind a full-screen app, an in-window indicator would be a capture indicator you could not see. Inside the app there is also a “Listening” chip beside the composer.

The menu-bar item shows every capture, not only the shortcut’s: the composer’s dictation, hands-free, and the Knowledge recorder each say when they hold the microphone. Every PersonalClaw window hears it too (the buddy shows its listening face), and so does the gateway, which tells your open pages. It clears when the capture stops, or when the window that captured closes or its page crashes, since its stream went with it. A plain browser tab has no shell to tell, so the browser’s own tab indicator is the one there.

Releasing the toggle ends the recording and stops the microphone track. The app does not hold an idle-but-open microphone between captures.

If you have not granted microphone access yet, the first capture asks. If you have already denied it, PersonalClaw cannot re-ask — macOS will not prompt twice — so it tells you that and points at Privacy & Security in System Settings.

System audio is not captured — microphone only

Section titled “System audio is not captured — microphone only”

PersonalClaw captures the microphone only. It does not capture system audio: not what your speakers are playing, not the other side of a call, not another app’s output.

This is a deliberate refusal, not an unfinished feature. macOS exposes no audio-only tap for system output; the only route is the Screen Recording entitlement’s audio side-channel, which would mean asking you for the right to record your screen in order to record sound. That is not a trade worth making quietly for a transcription feature, so there is no code path in PersonalClaw that captures system audio at all.

Probing the capability reflects this: system_audio reports unavailable with that reason on every platform, rather than reporting “not implemented” as though a later release will simply turn it on.

The desktop app can deliver notifications as real OS notifications instead of only as a badge on the dashboard’s bell. It is per notification kind, not a global switch: Settings → Notifications & Inbox → Notifications → the rules matrix → open a row’s detail → tick Desktop notification. Nothing is ticked for you.

Two things follow from where that switch lives:

  • A kind you have set to Badge or Digest never raises one, even with Desktop ticked. Those modes mean “do not interrupt me”, and an OS banner is an interruption. Only the Notify mode delivers natively. By default only approvals, questions and errors are Notify; a loop’s progress after each cycle is a Digest and every other kind a Badge, so ticking Desktop on one of those raises nothing until you set its row to Notify.
  • The dashboard is always the record. A native notification is an addition — the note still lands in the bell and the notifications feed. So nothing is lost when the desktop app is closed: the rule simply falls back to the dashboard delivery it would have had anyway, and the note’s stored detail says why (the desktop shell is not connected).

Clicking a notification brings PersonalClaw forward and opens the surface the note came from — an inbox alert opens Inbox, a loop’s progress opens Loops, a skill proposal opens Skills. A kind with no surface of its own opens the notifications feed.

Approvals, questions and errors look like the buddy. Their banner is silent, its icon is the buddy’s still orb for that alert (waiting with a ”!” for an approval, a ”?” for a question, settled with a red mark for an error), and its text is the one line the buddy would say, such as “Chat “Release notes” needs your OK: shell.run”, up to 120 characters. The line says what changed on its own, so the banner reads the same without its icon. Clicking it opens the buddy, as a click on its orb does, showing the alert first in the one order everything waiting on you is shown in. With the buddy off, it opens the item the alert is about in the app: the chat with the approval, the loop with the question. There are no answer buttons on the banner, since an answer needs its whole brief. Every other kind of notification sounds as before.

macOS never tells an app whether notifications are authorized, so PersonalClaw cannot show you a truthful “granted” state for this one and does not pretend to (Settings → Security → Desktop capabilities says as much). The first notification asks; after that, System Settings → Notifications & Inbox → Notifications → PersonalClaw is the only control. If you have turned them off there, ticking Desktop in a rule will silently do nothing — that is macOS’s answer, not a bug in the rule.

The buddy is a small window of its own that shows what PersonalClaw is doing and what is waiting on you, without opening the app. It is off until you turn on Buddy status, in Settings → Appearance → Buddy or with the menu bar’s Show Buddy: one switch, kept by your gateway, that every window and the phone follow at once. Turning it off closes the window. Settings → Appearance → Buddy also chooses which surfaces show it (the window, the menu-bar icon, the dock), and the app follows each. If the app starts before its gateway answers, it does what you last chose.

  • Where it sits. Docked, it hangs from the top centre of the display with the menu bar, just below the menu bar, so it covers no menu-bar item and no window control. On a Mac with a camera notch that puts it just below the notch, centred on it. Drag it more than 48 points down to float it anywhere; drop it within 96 points of the top centre to dock it again. A floating buddy stays on the display you dropped it on and is there after a restart; if that display is gone, it docks.
  • It never takes your focus. It shows without taking the keyboard, and takes it only when you click into it.
  • Clicks pass through it. Everywhere outside the buddy itself and its open card, a click reaches the window underneath.
  • Kept out of screen sharing and screenshots on macOS and Windows, by default, so what is waiting on you does not show in a share. Linux offers no way to keep a window out of a capture, so there the buddy shows in a share, and Settings → Appearance → Buddy says the row is not available on this computer instead of offering a switch.
  • It costs nothing while hidden. Hidden, its page schedules no timer and no frame and reads no pointer, and it opens no connection of its own.
  • It never keeps the app running by itself. Where closing the last window quits the app (no menu-bar item), the buddy closes with it.

It loads from the gateway this app started, signed in as the app’s own window is, and follows it when the gateway restarts. A route it opens, such as the chat that is waiting on you, opens in the main window. Its page can reach the app only through a handful of named calls (where the pointer is, a drag of the buddy, the room it needs, and opening a route), and the app checks each one; it has none of the main window’s desktop capabilities.

Settings → Appearance → Buddy holds every buddy setting in one place: Buddy status, which surfaces show it (its window, its tray and dock faces, its alerts’ notifications), and how long you are away before it steps back (docked it hides, floating it dozes; alerts still appear). They are kept by the gateway (buddy.*, see the configuration reference), so every window and every computer signed in to it follows the same answer, GET /api/buddy/policy, and a change applies at once, with no restart. The page also shows what the buddy follows from elsewhere, without a second copy of it: whether your notifications are muted or in quiet hours (changed in Settings → Notifications & Inbox → Notifications), and whether your system asks for reduced motion (changed in its accessibility settings). In the desktop app, its This computer rows say where the buddy sits on this computer, dock a floating buddy, and choose whether screen sharing and screenshots see it; those two are this computer’s own, kept by the app, not by the gateway.

A look you choose in one window, its colour scheme, its dials or its personality, is the look of every open window at once, the buddy’s included.

Its page is #/buddy, and a browser tab can open it too.

  • When it shows. Nothing while nothing is happening; a compact line while work runs; and when something waits on you, one request at a time, expanded with its brief, in the order every surface lists them (what it lets happen first, then the oldest), with how many more wait.

  • It never answers by itself. An answer is sent only from the request’s own controls (Allow or Deny, an option and Send, Dismiss) or ⌘Enter (Ctrl+Enter) while the request has focus. Nothing is sent when a request arrives, on a hover, when a timer runs out, or for a key pressed in another app. A request that names a second confirmation asks it first, and Escape closes it, deciding nothing. Each answer goes where the request’s own card sends it, with its words.

  • It keeps a request until it is decided. One answered somewhere else leaves saying so, and one past answering leaves as expired. No timer takes it away, and while you are dictating, or PersonalClaw cannot be reached, its controls are held.

  • It reads, it does not poll. It reads what is running and what waits on you again whenever either changes, so a missed update never leaves it showing something stale.

  • Approvals and agents’ questions are answered in the buddy. A workflow’s gate, a parked automation and the other kinds open in PersonalClaw.

  • Over a full-screen window of PersonalClaw’s own, only requests show, each as a quiet peek (the face and its badge), until you rest the pointer on it or click it. The app cannot see another app’s full screen.

  • Drag it to float it or dock it again, and the buddy goes with the window: a drag that moves it is never also a click.

  • Hide it for a while from its own menu (right-click it) or the menu bar: Hide for an Hour or Hide Until Tomorrow (the next midnight where you are). While it is hidden it shows nothing but its listening face, nothing waiting brings it back, and the menu bar and notifications keep telling you. Show Buddy Now in the menu bar ends it early; quitting the app does not.

  • While you are away (no keyboard or pointer for the buddy’s absence time, three minutes unless it is set otherwise, or the screen locked), a docked buddy hides and a floating one dozes. When you are back it says what happened meanwhile (“While you were away: 2 done, 1 needs you”).

Docked with nothing to say, the buddy keeps a strip at the top edge that draws nothing and passes every click through; rest the pointer there and it peeks. On macOS the app forwards the pointer’s moves to that strip, and nothing samples the pointer on a timer. Floating with nothing to say, or switched off, it hides its window, and the app shows it again when something waits on you that may interrupt you now, the same decision every other surface makes for that item: in quiet hours, or muted, it waits in the menu bar instead. The app holds one connection to the gateway for the menu bar and the buddy, and reads the lists when it says they moved, so nothing polls while it is connected; while it is down, the menu bar reads them every five seconds until it is back.

On Linux the area that takes clicks is the window’s shape, and the dock and float land without a move. Linux offers an app no way to keep a window out of a capture, so a screenshot or a share there shows the buddy.

The shell ships for macOS (Apple silicon and Intel) and Linux x86-64. There is no Windows build — see below for exactly why and what would change that.

macOS — .dmg, not notarized, and one approval on first launch

Section titled “macOS — .dmg, not notarized, and one approval on first launch”

Every release attaches two dmgs, built by CI from the same tree as the release tag:

  • PersonalClaw-<version>-arm64.dmg for a Mac with Apple silicon;
  • PersonalClaw-<version>-x64.dmg for an Intel Mac.

Not sure which you have? Apple menu → About This Mac: a Chip line naming Apple M1 or later is Apple silicon, and a Processor line naming Intel is Intel. Open the dmg for your Mac and drag PersonalClaw to Applications.

Do not use the one-click Install button — it cannot work on this build. Recent macOS versions offer an Install affordance when you open a .dmg. Clicking it here fails with:

Could not install. Nothing was changed. You can still drag the app to Applications.

That dialog is expected, and it is telling you the truth. Your download is not corrupt and nothing needs retrying — macOS reserves the one-click install path for apps signed with a Developer ID and notarized by Apple, and this one is deliberately neither (what it is signed with: below). Clicking Install again will produce exactly the same dialog, because the artifact has not changed. The supported path is the one the dialog itself names:

  1. Drag PersonalClaw to Applications (the dmg window shows both the app and an Applications shortcut for exactly this).
  2. Approve it once under System Settings → Privacy & Security — the next section.

It is not notarized, and unlike Linux that costs you one step. Gatekeeper does consume a signature on macOS, so the first launch will not work by double-click — macOS will say the app “cannot be opened because the developer cannot be verified”. To approve it once:

  1. Try to open the app (double-click). Let macOS refuse.
  2. Open System Settings → Privacy & Security, scroll to the message about PersonalClaw, and click Open Anyway.
  3. Confirm. macOS remembers the decision — you will not be asked again for this build.

That is the whole cost, and it recurs once per installed version. Removing it would require a paid Apple Developer account for notarization; the project has deliberately not taken that on, so where you downloaded it is the integrity story — get the dmg from the GitHub Release page only.

What “not notarized” means precisely, because “unsigned” is the word people reach for and it is not accurate. The app is code-signed, with an ad-hoc signature: one that carries no identity, no certificate and no Apple account, and that every arm64 app needs simply to be allowed to execute. What it does not carry is a Developer ID signature and Apple’s notarization, which is what Gatekeeper and the dmg’s one-click Install actually ask for. So the signature you can verify locally is a genuine integrity check over the bundle’s contents — codesign --verify --deep --strict /Applications/PersonalClaw.app should exit cleanly, and it will fail if a single file in the app was altered after it was built — but it proves nothing about who built it. That is why the download source is the integrity story.

One dmg per kind of Mac. The dmg carries a PyInstaller-bundled backend, and a frozen Python binary cannot be cross-compiled, so each dmg is built on a CI runner of its own architecture: macos-26 for Apple silicon and macos-26-intel for Intel. Each release checks that the app and its backend in each dmg are built for that architecture alone, then starts both from the mounted dmg on that runner. There is no universal dmg: it would be twice the download.

The Intel build carries a cryptography compiled by CI. cryptography, which the backend uses for its encryption, has published no build for Intel Macs since its 49.0.0. So on the Intel runner, CI builds the exact release the lock file pins from its source, checked against the lock’s hash, and links OpenSSL into it statically: the runner’s OpenSSL 3, 3.6.3 when this was written, and the release’s build record names the one each release carries. The Apple-silicon dmg carries cryptography’s own published build. personalclaw doctor --crypto shows what yours carries and checks that it works.

Every release attaches two Linux artifacts, built by CI from the same tree as the release tag:

  • PersonalClaw-<version>.AppImage — self-contained: chmod +x it and run it.
  • personalclaw-desktop_<version>_amd64.deb — install with sudo apt install ./personalclaw-desktop_<version>_amd64.deb.

Neither artifact is code-signed, and that is deliberate, not a gap. Linux has no OS-level signing gate — nothing analogous to macOS Gatekeeper consumes a signature on an AppImage or a .deb — so a signature would change nothing your system checks. What you will actually see:

  • The AppImage runs after chmod +x with no provenance prompt at all, which is exactly why where you downloaded it is the whole integrity story. Get it from the GitHub Release page only.
  • apt will not warn about the .deb either: repository GPG signing applies to packages served from an apt repository, and this file installs directly. Same rule — download from the release page.

(App bundles installed inside PersonalClaw are a separate, signed story — see artifact signing.)

One Linux-specific behavior worth knowing: the menu-bar presence above depends on your desktop environment offering a tray. On one that does not, the shell notices — closing the window then quits for real instead of hiding, exactly as described under “Closing the window is not quitting”, so you can never strand a running app you cannot reach.

From a checkout, make desktop-dist builds the dmg for the Mac it runs on (arm64 on Apple silicon, x64 on Intel) and make desktop-dist-linux builds the AppImage and .deb on x86-64 Linux: the targets the release’s desktop-mac and desktop-linux jobs run, in the venv those jobs make (.github/workflows/release.yml).

There is no Windows shell, and none is planned until both of these change:

  1. The native-Windows audit ruled the backend port no-go (its “Go / no-go” section): a native port would silently weaken file-permission and sandbox guarantees the rest of the system depends on. That doc’s demand-evidence criteria are the flip condition.
  2. Windows code-signing secrets exist. None do — and an unsigned Windows executable is SmartScreen-hostile in a way an unsigned AppImage is not: users would see a scary “unrecognized app” interstitial on every install.

The desktop shell follows platform support, never leads it. Windows users have real, tested backend paths today: WSL2 or Docker Desktop.

The app updates itself when you ask it to. It looks for a new release a minute after it starts and then once a day, and at once when it finds the gateway it uses on a newer version than itself (one you updated from a browser tab, say), and says so in two places: Settings › Updates › This app, and a row in the System status card while a new version is on offer. PersonalClaw › Check for Updates… (on Linux, Help › Check for Updates…) looks now and opens This app. It takes two presses. Update downloads and checks the new version in the background, and changes nothing beside the app; when it is ready, This app and the row say Restart to Finish the Update. That press, once you confirm, installs it; the confirm says whether your gateway restarts with the app, and how many running agents that interrupts. Nothing is downloaded before the first press, and nothing in Applications changes before the second.

What Update does:

  1. The app reads the release list from GitHub and takes that release’s copy for this computer and nothing else: on macOS exactly PersonalClaw-<version>-<arch>.dmg, from an AppImage exactly PersonalClaw-<version>.AppImage. The download goes to GitHub’s release hosts only, with no credential, into a private folder of its own in the app’s own data folder (readable by your account only, and never emptied by the system’s temp cleaning), and is checked against the size and sha256 digest GitHub publishes for that file; a copy that differs is not used.
  2. On macOS the disk image is attached read-only, and the app in it must be PersonalClaw.app with this app’s bundle id (io.personalclaw.app), the release’s version, an intact seal (codesign --verify --deep --strict) and this Mac’s architecture. It is copied out of the image into that private folder, still sealed, and waits there. Quitting without finishing removes it, a download still under way included; a folder a quit left behind is removed at the next start, unless a disk image in it can’t be detached; that folder is left, and the log says so.
  3. While it waits, the home’s update settings still hold: a pin or a channel set after Update that no longer allows that version drops it, at the next check (Check now reads them again, and asks GitHub only once they no longer allow it) or at Restart to Finish the Update.

What Restart to Finish the Update does:

  1. The checked copy is used only while it is still the one that was checked: its folder the same one, your account’s and readable by you only. It is copied beside the running app as .PersonalClaw-<version>.app.incoming and checked again there: the bundle id, the version, this Mac’s architecture, and exactly the build the disk image held (its CDHash); an AppImage must still match the release’s digest. A copy that is gone by then is no failure: the app says so and offers Update again. The CDHash holds the copy to that build while it waits and against other accounts on this Mac; it is no guard against a program running as you, which could change the image as it downloads (an account that is already compromised is outside the scope of SECURITY.md). Then the app quits as it always does (it signs out and stops its gateway), and only then does the new copy take the old one’s place: the old one moves to .PersonalClaw-<old>.app.previous beside it, the new one to PersonalClaw.app. The app starts again, on the new copy.
  2. Once the new copy and its gateway are up, the old copy goes to the Trash. Until then it is kept: if the new one doesn’t start, move it to the Trash and rename the old one back (it is hidden; in Terminal, mv /Applications/.PersonalClaw-<old>.app.previous /Applications/PersonalClaw.app).

The next start says how it went: This app reads “Updated from 0.3.7 to 0.3.8.”, or, when the new copy could not be put in place, that this copy is unchanged, and Settings › Updates opens on it. An AppImage replaces itself the same way, the old file kept beside it until the new one starts. Your data lives in ~/.personalclaw and is untouched by any of it.

Where it can’t update itself, it says why and points at the releases page, as every failure to install does:

  • a copy run from its disk image, or one macOS runs from a temporary copy because it was opened where it was downloaded: move it to Applications first;
  • a copy renamed from PersonalClaw.app, or in a folder this account can’t write to (a standard account and /Applications);
  • the .deb: install the new package over it, sudo apt install ./personalclaw-desktop_<new>_amd64.deb;
  • a development run (npm start), which updates from its checkout.

When you press Restart to Finish the Update, macOS may ask once whether PersonalClaw may change apps (System Settings › Privacy & Security › App Management): allow it, or decline and install from the releases page. Update alone never asks: it writes nothing in Applications. A permission macOS gave the old copy (the microphone, notifications) can be asked for again by the new one, as after installing it by hand: the app isn’t notarized, so macOS ties those to each build.

The System status card’s own Update and Home’s Update available stay the gateway’s. On the app’s own gateway they restart nothing and say how that install is updated: the app’s Check for Updates…, or the releases page. On a gateway the app did not start (one already serving your home), they are that gateway’s: one installed with pip updates itself as it does in a browser, and the app follows it through the restart. The app’s row is about the app alone. A browser tab, or a paired gateway’s window, has no app to ask, so it shows neither This app nor the row.

The updates block is honored on this install, by the gateway’s check and by the app’s own; the app reads it from ~/.personalclaw/config.json at each check, so a change in Settings holds from the next one. A file it can’t read offers nothing: the pin it may hold is a limit the app won’t drop, so This app says the file couldn’t be read instead.

  • Channel (updates.channel) — stable (default) watches normal releases, beta watches release candidates too. nightly tracks a git branch, so it has no meaning for a packaged app; the resolver and the app treat it as stable here.
  • Version pin (updates.pin) — pin 0.1.3 and neither the panel nor the app offers newer releases, which is how you stay on a known-good build while you finish something. It must be an exact release version; a pin that matches no published release is flagged rather than silently stopping updates. Clear it to follow the channel again. The app follows the pin while it runs its own gateway; a gateway it found serving your home is pinned by its own install. A pin older than the app is said, not installed: the app doesn’t roll back.
  • Roll back — download the older release from the releases page and install it over this one, then set updates.pin to that version so neither the panel nor the app offers the newer one again. Run personalclaw snapshot first: pre-1.0 releases carry no data migrations in either direction. Your home then remembers the newer release, and the older app’s gateway is refused it until the rollback is said to be meant, once, by a start of its own: quit the app, run the personalclaw-backend in the app’s resources/backend-dist/personalclaw-backend/ folder from a terminal as PERSONALCLAW_ROLL_BACK_FROM=<the newer version> <that program> gateway (on macOS, /Applications/PersonalClaw.app/Contents/Resources/backend-dist/personalclaw-backend/personalclaw-backend), stop it with Ctrl-C once it serves, and open the app. The app never passes that variable on to its own gateway. (The one-click Roll back to v<previous> button is a git/pip affordance — there is nothing for it to install here.)
  • Apply updates (updates.auto) — not offered on this kind: the app installs only when you press for it, so staged notifies exactly as off does. The field stays in the config because the same config file follows your ~/.personalclaw to other install kinds.
  • Automatic update checks (updates.check_enabled + updates.check_interval_hours) — the same switch as everywhere else. Off, neither the gateway nor the app asks GitHub on its own: the panel’s Check now and Check for Updates… each look once, when you press them. On, the gateway asks when it starts and then once every check_interval_hours (default 12), and the app a minute after it starts, once a day, and when it finds its gateway on a newer version.