Claude Buddy v0.5.10-beta

A features-and-fixes release. Cloud sessions can now be sent to, stopped, archived and deleted from Buddy; New chat can start Codex and Grok sessions under any of your accounts; a far machine's agent team draws every member, linked to its lead; and Windows gets a round of fixes, most visibly badges that render properly instead of as colour emoji.

New

• Talk to a Claude Code cloud session from its chat panel. Send messages into a running cloud session and stop it, from the same panel you already use for local sessions. A live cloud session's panel also has its browser link back.
• Archive or delete a cloud session from its orb's right-click menu.
• Cloud orbs for every account. Buddy reads every Claude Code account you're signed into for cloud sessions, and sends with the login that owns each one. A login under a custom config directory is found, and a blanked login reads as signed out instead of as an error.
• New chat can start Codex and Grok sessions under a chosen account, not only Claude Code ones.
• A far machine's agent team draws every member. When both machines run Buddy and are linked directly, each team member gets its own smaller orb, with its own initials and colour and an arrow to its lead — the same as a team on this machine. A machine without Buddy still shows nothing.
• Usage orbs have their own switch and hotkey, separate from the session orbs.
• Separate Speech and Alert volume sliders, and a button that previews a Speak voice from the settings window.

Fixed

• Windows badges and button marks are drawn, not turned into colour emoji. Windows was replacing several symbols with emoji, which looked wrong and ignored the orb's colours.
• Only one Buddy per user on macOS. Starting Buddy from a second login session no longer gives you two copies, and installing a new build no longer leaves the old one running beside it.
• Buddy stays responsive with many sessions open. Reading what is under each session, agent-team membership and turning on file watchers all moved off the UI thread; with many sessions these could freeze the orbs for seconds at a time.
• A turn's sound no longer plays twice when two turns finish close together.
• Speech says "Spend limit reached" instead of "Summary unavailable" when that's the reason, and the summariser passes its instruction as an argument rather than on stdin.
• New chat under a named account starts with that account's login on the first try.
• Windows text-to-speech handles any text and voice name, including quotes and non-ASCII characters.
• Windows file properties show the real version number, and the installer's PowerShell scripts run under Windows PowerShell 5.1 as well as PowerShell 7.
• The Remote Control panel no longer refers to the old relay, which was removed in an earlier release.

Behind the scenes, a long list of intermittent test failures on both platforms were traced to their real causes and fixed, and the coverage tooling now measures every suite on Windows and refuses to report a number it didn't actually measure.

Known limitations

• A far machine's agent team is drawn only when that machine also runs Buddy and is linked directly.
• A per-user Windows install adds no firewall rule for the peer link, because that needs admin rights. Windows asks the first time Buddy listens.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.10-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.10-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.10-beta-win-x64-setup.exe

Upgrading

Replace the app as usual. On macOS, if you re-install you have to re-grant the Automation and Local Network permissions. Replacing /Applications/Claude Buddy.app gives the app a new code identity, and macOS doesn't carry those permissions over to it. Without Automation, click-to-focus stops working; without Local Network, anything on your LAN, such as an OpenClaw gateway or a remote-control peer, can't be reached. Re-grant both in System Settings → Privacy & Security.

Claude Buddy v0.5.9-beta

A performance release. Claude Buddy's idle CPU on macOS drops from about 37%, and it stops streaming about 100 MB a minute to its remote-control peers. Animations also run at their proper speed for the first time.

Fixed

• Animated persona pictures, pulses and hover timers now run on time. Every timer in Buddy had been firing about 100–200 ms late since the UI thread started being claimed before the native platform was up: the dispatcher kept the clock it was created with, while the platform scheduled timers against a later one. An animated persona that should play at 25 fps showed about 4. Timers now run on the platform's clock. Pulses and the danger-ring breath are capped at 10 fps, and idle orbs breathe at 5, so the extra accuracy doesn't cost CPU.
• Idle CPU on macOS is much lower. It was about 37%; it's about 9% with three animated personas and networked features off, and 15–19% with everything on. A usage ring in the danger band "breathes", and that breathing was an animation that never ended, so the app redrew on every screen refresh for as long as the ring stayed there. It now breathes on a 20 fps timer. It looks the same, but costs a fraction of the work.
• Remote-control peers no longer stream megabytes every 10 seconds. Each peer poll resent every persona picture in full, so 11–15 MB animated GIFs went out every 10 s to each peer, about 106 MB a minute. Now a roster that hasn't changed gets a short "unchanged" reply, and persona pictures are sent once and then referred to by fingerprint. Peers running an older build still work, at the old cost, until they're updated.
• A Mac that stays locked no longer loses Buddy after 12 hours. On a headless or always-locked Mac, Buddy waited 12 hours for an unlock, then tried to start its window anyway and crashed. Now it keeps serving its peers for as long as the screen is locked, and starts its window only when an unlock actually happens.
• Fewer claude agents --json launches. Buddy now asks only the Claude Code accounts that have a session on screen, and still asks every account whenever a session can't be traced to one.
• Hidden orbs no longer keep animating. With orbs turned off, animated persona pictures stop and pick up again from the same frame when the orbs come back.
• The Windows installer no longer exits with an error on a per-user install. The firewall step needs admin rights, so it now runs only on an administrative install.

Known limitations

• A per-user Windows install adds no firewall rule for the peer link, because that needs admin rights. Windows asks the first time Buddy listens.
• The remaining ~10% idle CPU on macOS hasn't been investigated yet.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.9-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.9-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.9-beta-win-x64-setup.exe

Upgrading

Replace the app as usual. On macOS, if you re-install you have to re-grant the Automation and Local Network permissions. Replacing /Applications/Claude Buddy.app gives the app a new code identity, and macOS doesn't carry those permissions over to it. Without Automation, click-to-focus stops working; without Local Network, anything on your LAN, such as an OpenClaw gateway or a remote-control peer, can't be reached. Re-grant both in System Settings → Privacy & Security.

Claude Buddy v0.5.8-beta

Resizable orbs, a fix for Claude Buddy slowing to a crawl when many tmux sessions are open, an Account picker for New chat, and Interrupt and End for OpenClaw orbs.

New

• Orbs are resizable. A new Size slider under Settings → Orbs sets how big every orb is, from 60% to 200% on macOS and 70% to 200% on Windows. Right-click any orb and choose Size to set that one orb on its own, or choose Default to have it follow the slider again. Each agent remembers its size across restarts. When orbs of different sizes are arranged together, the shape is spaced for the largest orb, so nothing overlaps. The settings are orbSize and orbSizes in settings.json.
• New chat can start a Claude Code session under a second account. When you've configured more than one Claude Code profile (CLAUDE_CONFIG_DIR), the New chat dialog shows an Account picker. It stays hidden for Codex, Grok and OpenClaw, and when only one account is configured.
• Interrupt and End on an OpenClaw orb. An OpenClaw orb's right-click menu now has rows to interrupt the current run and to end the conversation.

Fixed

• Claude Buddy no longer grinds to a halt when many tmux sessions are open. On every scan, about every two seconds, Buddy used to run tmux and a full ps listing for each session in a tmux pane, one after another on the thread that draws the UI. With a dozen or more sessions open, menus, dragging and chat panels all became sluggish. That work now happens in the background, with one ps and one tmux list-panes per tmux server per scan. This had been in every release since 0.5.4-beta.
• Dragging an arranged shape sideways no longer gets lost after re-arranging. The saved position of an arrangement could drift past the edge of the screen, and after that, drags back toward the screen were absorbed. Buddy now saves where the shape actually landed, and repairs an out-of-range position the first time you arrange.
• The New chat dialog no longer freezes stretched and unclickable on macOS after switching between Claude Code and another CLI.
• A team member's own profile file now decides its whole persona. A member profile that named itself but no picture used to take its picture from the lead's persona instead, so the orb wore the lead's face.

Known limitations

• Orb sizing and mixed-size arrangements were checked on a real Windows desktop at 100% display scaling, and orb sizing was tried by hand on a Mac. Display scaling other than 100% on Windows hasn't been tried.
• On Windows, one more slow call still runs on the UI thread when a new session appears (CB-212).
• Orbs smaller than 70% aren't offered on Windows. Windows won't make a window shorter than 39 pixels, and the strip left under a smaller orb would catch clicks.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.8-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.8-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.8-beta-win-x64-setup.exe

Upgrading

Replace the app as usual. On macOS, if you re-install you have to re-grant the Automation and Local Network permissions. Replacing /Applications/Claude Buddy.app gives the app a new code identity, and macOS doesn't carry those permissions over to it. Without Automation, click-to-focus stops working; without Local Network, anything on your LAN, such as an OpenClaw gateway, can't be reached. Re-grant both in System Settings → Privacy & Security.

Claude Buddy v0.5.7-beta

A small release: a global hotkey for New chat, New chat getting a tmux window of its own, and WSL sessions on Windows getting their orbs back.

New

• Ctrl+Alt+N opens New chat from anywhere. If New chat is already open, the hotkey brings it to the front instead of opening a second one. To use a different chord, set newChatHotkey in settings.json, the same way toggleOrbsHotkey works.

Changed

• New chat now opens in a tmux window of its own in your tmux session. It used to split the window you were working in.

Fixed

• WSL sessions on Windows now get orbs. A Claude Code session running inside WSL never drew an orb, while the same session started from a Windows prompt did. This is fixed by updating the app. The hooks don't need reinstalling.
• A missing folder, or one with #{ in its name, no longer starts Claude in your home folder under tmux. This applies to New chat and to attaching from an orb. tmux quietly fell back to $HOME; the command now fails instead of running in the wrong place.
• An invalid hotkey override no longer binds a key you can't press. Values such as Ctrl+Alt+5, F5 or Ctrl+999 used to be accepted and bind a key nobody could press, or no key at all. Both hotkeys now fall back to their default. Only A–Z and 0–9 are accepted as the key.
• A hotkey the OS refuses is now logged to hotkeys.log, next to crash.log, so a chord another app already holds shows up somewhere instead of failing silently.
• Choosing New chat… from the tray when it's already open now brings it in front of other apps. Before, it only moved to the front of Claude Buddy's own windows.

Known limitations

Ctrl+Alt+N has been checked by hand on macOS. It has not yet been checked by hand on Windows, where it is covered only by the automated tests.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.7-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.7-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.7-beta-win-x64-setup.exe

Upgrading

Replace the app as usual. On macOS, if you re-install you have to re-grant the Automation and Local Network permissions. Replacing /Applications/Claude Buddy.app gives the app a new code identity, and macOS doesn't carry those permissions over to it. Without Automation, click-to-focus stops working; without Local Network, anything on your LAN, such as an OpenClaw gateway, can't be reached. Re-grant both in System Settings → Privacy & Security.

Claude Buddy v0.5.6-beta

Claude Buddy can now start a chat as well as watch one, and when it opens a terminal in iTerm2, Claude Code is actually running in it. Those two are this release.

0.5.5-beta was a single crash fix. This one clears everything that has landed since: two features, four fixes you would have noticed, and two that make the test suite trustworthy.

Still a beta. What was and was not verified on a real machine is in Known limitations.

New: start a chat from Claude Buddy

Until now Claude Buddy only ever observed sessions. New chat… in the tray menu opens a small dialog: pick Claude Code, Codex, Grok or OpenClaw, pick a folder (recent session folders first, then Browse…), and press Start. New chat here on an orb's context menu opens the same dialog already filled in with that orb's folder and CLI.

For OpenClaw the folder field becomes an agent picker, and Start creates a conversation on the gateway and opens a chat panel on it.

A kind that can't be used is shown disabled, with the reason on screen: the CLI wasn't found, no gateway is configured, or replying to agents is turned off in Settings. A launch never fails silently. If no orb shows up within about twenty seconds of a successful start, the dialog says so.

New: a sound when a turn finishes or a session needs you

A new Sounds section in Settings plays a sound when a turn finishes and a different one when a session is waiting on you. It has a preview for each. The choices are your system's own sounds or a file you pick, so nothing is bundled. Each orb can override the default from its right-click menu, under Sound.

Turn finished can instead speak a short summary of what was done, in the orb's own voice. Sounds from one scan are merged into one, attention wins over finished, and there is always at least two seconds between sounds. So a burst of agents finishing at once gives you one chime, not a chord.

Fixed: iTerm2 opened a blank window instead of Claude Code

If iTerm2 is your terminal, every "open a terminal" path handed iTerm2 a shell command line it doesn't run through a shell. That covers opening an agent team's view, attaching to a teammate, and the new New chat dialog. iTerm2 tried to execute a program called cd. Depending on the moment, you got either a blank window and "Couldn't open a terminal for Claude Code", or, worse, a plain shell in your home directory while the app reported success. This dates from 0.5.4-beta.

iTerm2 now starts your own login shell ($SHELL, falling back to /bin/zsh for anything that can't parse the line) as a login, interactive shell. Your .zshrc PATH applies, so a claude under ~/.local/bin or a node under nvm is found. The line goes to iTerm2 base64-encoded, because iTerm2's own argument splitter interprets backslashes even inside single quotes, and a folder name may legally contain one. Folders with spaces, apostrophes, quotes, $ or ~ in their names now open exactly where they should.

The same change fixes a quieter bug on both iTerm2 and Terminal.app. With zoxide set up as your cd, a folder that no longer existed could fuzzy-match a similarly named project and start Claude there. It now fails the cd and runs nothing.

Fixed: OpenClaw orbs never glowed while replying

An OpenClaw conversation replying to you left its orb dark. Only cron jobs lit up, because the original rule had been built from a cron job's events, and an ordinary run reports itself differently. The orb now glows for any run in flight, on a rule that counts an event as work only when its shape was measured to mean work, rather than on a blocklist of events that don't.

Fixed: cloud sessions vanished after "Keep orbs for"

A cloud session you hadn't typed into recently lost its orb once the "Keep orbs for" window passed, even though it still exists and can be resumed at any time. That setting is about local sessions, where a quiet status file usually means a process that exited without saying so. A cloud session has no process to exit, so it now keeps its orb until you archive it.

Fixed: a persona lost its picture one folder down

A persona set up with profile-gen kept its name and lost its picture, drawing letters instead, whenever the session sat in a subfolder of the project rather than the project folder itself. profile-gen writes the picture's path relative to the project folder. Claude Buddy only looked for it next to the persona file, which doubles the path, and under the session's current folder, which is only the project folder while you stay in it. One folder down, both missed.

Claude Buddy now remembers which folder level of its upward search found the persona, and looks for the picture there too, after the persona file's own folder and before the current folder. Verified on a real Mac: an orb in ~/Documents now shows the same portrait as one in ~, where it used to show the persona's initials.

Two deliberate widenings come with it. If the same picture name exists under both the project folder and your current folder, the project folder's copy now wins; before, the current folder's did. And a persona found from your home folder may use any picture under your home folder, because containment is checked per root and that root is ~.

Fixed: the test suite told the truth about itself, again

Two changes with no user-visible effect. The UI suite sometimes reported one test fewer than it has, with no failure and a clean exit. The cause was the test framework resetting the UI dispatcher before every test, which let a leftover background thread claim it. It now runs under one dispatcher: 30 runs before the change showed two short counts, and 30 after showed none. A flaky OpenClaw handshake test was also made deterministic.

Known limitations

The iTerm2 fix was verified on a real iTerm2 3.7.3. That covers New chat and the agent-team launches, every command shape, 14 hostile folder names and bash, sh, dash and ksh as $SHELL. It was not verified by clicking Start in the installed app, on the path that places a new chat in an existing tmux session, or against real bash or ksh users' dotfiles. If a folder is deleted in the instant between New chat checking it and the terminal starting, iTerm2 briefly opens a window that closes, with no error in the dialog. A returned window proves a window opened, not that the command in it ran. If you use oh-my-zsh's dotenv plugin, it may ask "Source it?" in the new window, as it always has in Terminal.app.

Claude Code itself refuses a working directory containing a backslash, even when started by hand. That is upstream.

Windows is unaffected by the iTerm2 fix, which is macOS-only by construction. Both platforms run the full suite in CI.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.6-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.6-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.6-beta-win-x64-setup.exe

Upgrading

Replace the app as usual. On macOS, replacing /Applications/Claude Buddy.app gives the bundle a new code identity, and macOS re-evaluates the Automation and Local Network permissions against it. If click-to-focus or anything on your LAN stops working after an upgrade, look there first.

Claude Buddy v0.5.5-beta

Claude Buddy no longer dies overnight while your screen is locked. That is this release.

0.5.4-beta shipped a few hours ago and cleared a week of backlog. This one is small and deliberate: five pull requests, one of which fixes a crash that had been in the app since at least 7 September, and four of which make the test suite tell the truth about itself.

Still a beta. The crash fix was measured against the real failure on a real Mac; what was and was not verified is in Known limitations.

Fixed: the app started into a locked screen and aborted

If Claude Buddy launched while your screen was locked — a login item on a machine you had walked away from, or a keep-alive restart overnight — it waited for the screen to unlock, gave up after two hours, and then started anyway into a screen that was still locked. CoreVideo refused, nothing caught it, and the process died. On a machine left locked overnight it would die and stay dead until somebody came back and noticed.

The wait function had the answer the whole time. It returned a bool meaning "the cap expired and the screen is still locked", and the code that called it took that as an Action — so the answer was discarded by the signature, silently, and the app started regardless.

It now distinguishes three states rather than two. The window server saying nothing at all is genuine ignorance and still bounded. The window server saying the screen is unlocked starts immediately, as before. The window server saying the screen is locked now waits — up to twelve hours rather than two, because in that state the app demonstrably cannot draw, and the alternative to waiting is a crash.

Twelve hours is a bound rather than an absence of one, and that is the deliberate part. If the lock signal were ever wrong, an uncapped wait would mean the app is simply never there, with no menu-bar icon and no way in — and this project would rather have a crash it can recover from than a silence it cannot. An expired bound starts the app; if the screen really was locked, the crash restarts under the keep-alive and tries again.

Fixed: the test suite told the truth about itself

Four changes with no user-visible effect, kept together because they are one story.

Two tests failed intermittently on loaded machines — one racing a five-millisecond timer against its own teardown, one racing another test class for a shared directory. The second turned out to be reachable three calls deep from any test that refuses a persona picture, which is why three separate attempts to fix it by listing the classes involved each found one more class the last had missed.

It is now fixed structurally instead: a test's scratch log directory has no process-wide name at all, so a test that forgets to isolate cannot reach another's. A guard pins that to a single read site so it stays true. And a side effect nobody had filed — test runs writing entries into the real ~/Library/Logs/ClaudeBuddy — stops too, which matters the next time somebody reads that file to diagnose a genuine crash.

One claim in this repository's own contributor documentation was also wrong and is corrected: a background job does get a window server session, contrary to what the file had said for months, and an arm of the crash fix had been justified on that.

Known limitations

The locked-screen path was verified by reading the state off a second Mac that was genuinely locked, over SSH, rather than by locking the machine under test — so the behaviour is measured, not inferred. The crash itself was reproduced from its own crash log and system power log.

Not verified: that this specific crash on 22 September took the locked branch rather than the unknown one. After the fix both branches are correct and the crash is prevented either way, so the question no longer decides anything — but the causal claim is narrower than "we know exactly what happened", and it is stated that way.

Windows is unaffected by the crash fix, which is macOS-only by construction, and was not driven by hand. Both platforms run the full suite in CI.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.5-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.5-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.5-beta-win-x64-setup.exe

Upgrading

Replace the app as usual. On macOS, replacing /Applications/Claude Buddy.app gives the bundle a new code identity, so the Automation and Local Network permissions are re-evaluated against it — if click-to-focus or anything on your LAN stops working after an upgrade, that is where to look first.

Claude Buddy v0.5.4-beta

A week of orbs, personas and settings you can actually search. That is this release.

0.5.3 shipped 15 September. Since then 48 pull requests landed on develop and none of them reached a user, because main — the branch every installer is built from — has not moved. That includes the fix this release exists to ship: CB-118 corrected the URL a screenshot-comment image is built from, and it has been sitting merged and reported done for four days while doing nothing at all, because publish-screenshots.yml is a workflow_run workflow and GitHub always runs the copy on the default branch — main — regardless of what develop holds. It only looks fixed because this repository happens to be public right now; the moment it is private again, every screenshot image in every PR comment 404s for a human reading it in a browser.

Still a beta. What follows is a large batch — see Known limitations for what has and has not been run on a real machine.

New: orbs for sessions running in Anthropic's cloud

A Claude Code session running in Anthropic's cloud now draws an orb beside your local ones, with its real state, a context ring, and its post-turn summary on hover (CB-164). Clicking it opens the session in your browser; the flyout's keyboard button opens a read-only transcript panel. Off by default.

New: paired machines mirror Codex, Grok, and personas

A paired machine's Codex and Grok sessions now mirror over the direct peer link the same way its Claude Code sessions already did (CB-162), and a mirrored session draws wearing its own persona — name, portrait and voice — resolved on the machine that owns the CLAUDE.md, never guessed from a path shared between two machines that happen to check the same project out in the same place (CB-163).

New: a speaker mode for a reply too long to listen to

The speaker button gains a mode. Full response reads everything the assistant said, same as always. Vibe code summary asks a separate, throwaway claude -p --model haiku process for two or three sentences instead — a different process, a different conversation, nothing written into your transcript (CB-165). A short reply is read in full either way; summarizing one that's already brief would buy silence for nothing.

New: fold a settings section, or just search for it

The settings window had grown to thirteen sections in one long scrolling column. Every section now folds and remembers how you left it, and a filter box at the top narrows the whole page to whatever you type (CB-166). Everything is expanded on a fresh install, so first launch looks exactly as it did before.

New: a global hotkey to hide every orb at once

Ctrl+Alt+H (Windows) toggles every orb hidden or visible from anywhere, with the binding built to take more hotkeys later (CB-155). Uses Carbon on macOS specifically because it needs no Accessibility or Input Monitoring permission.

New: pinned chat panels survive a restart

A panel you pin now remembers that it's pinned, and where you left it, across quitting and relaunching the app (CB-111) — the persistence CB-110's own description asked for and didn't yet have.

New: Claude Buddy comes back after a crash

Nothing shipped by this repo brought the app back if it crashed, on either platform (CB-49). macOS gets a launchd KeepAlive agent; Windows gets a Scheduled Task triggered off the OS's own Application Error event. Opt-in, gated behind the existing "Serve on launch" setting — a keep-alive that returns after every exit, including a deliberate quit, is the "app that will not stay quit" the ticket itself warns against.

Fixed

• Screenshot comment images no longer 404 for a human with full read access to a private repo (CB-118) — see above for why this alone did not take effect until now.
• The fork-PR lookup publish-screenshots.yml runs against no longer matches nothing (CB-117).
• An AGENTS.md/CLAUDE.md persona no longer needs unwrapping, and generated personas stay out of git.
• Windows background-orb clicks work, and a background Claude Code attach resolves Claude.exe correctly.
• An unattributed room turn draws no chip; a repeated message and a quoted one both survive in a room instead of one eating the other (CB-32, CB-33).
• A failed send keeps what you typed instead of clearing the composer (CB-35).
• Orb arrangement no longer relocates every orb just because one ended (CB-161); scroll-to-end settles once the extent actually stops moving instead of after two ticks (CB-160).
• A picture drawn by both an inline block and its delivery mirror no longer duplicates (CB-98).
• iTerm2/Terminal.app is asked to run a command instead of being handed a script file to open (CB-80).
• A stuck OpenClaw conversation nobody is looking at is let go instead of held forever (CB-92); a failed avatar decode is retried instead of cached as a permanent failure; a delivered message live-updates the open chat panel (CB-95).
• The Voice and Avatar fields in a settings table row are scoped to the persona section they belong to (CB-145).
• A session can no longer be ended out from under the background daemon it's hosting.
• Duplicate-launch handling exits cleanly instead of aborting the dispatcher (CB-178); Claude Buddy's own internal CLI processes no longer draw a stray orb for themselves.
• An unknown tmux pane owner is no longer treated as a mismatch; an attached-but-unaimable tmux client no longer opens a second tab (CB-158).
• The account app's own default-account jobs are asked for even when this instance inherited a different account already running (CB-114).
• The OpenClaw receive loop runs on its own thread instead of borrowing the thread pool, closing a concurrency hang at handshake.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.4-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.4-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.4-beta-win-x64-setup.exe

The ClaudeBuddySpeech-0.5.4-beta-*.zip assets are the optional high-quality voice engine. You do not download these yourself — the app fetches the right one when you turn the setting on. They are published here because that is where it looks.

The .NET runtime is bundled; nothing else is needed. SHA256SUMS.txt covers every file — verify with shasum -a 256 -c SHA256SUMS.txt on macOS or Get-FileHash <file> -Algorithm SHA256 on Windows.

Upgrading from 0.5.3-beta

macOS: replace the app in Applications. The signing identity is unchanged, so Automation permission and click-to-focus carry over.

Local Network permission does not. Same CDHash rule as every prior release: replacing the app loses the grant, and paired machines plus an OpenClaw gateway start failing with No route to host. Approve it again in System Settings → Privacy & Security → Local Network. A headless Mac still cannot; pair from the machine with a screen and add the headless one by address.

Windows: run the new setup over the old one; it upgrades in place and leaves your hook configuration alone.

Crash keep-alive and the global hide-orbs hotkey are both off/default until you turn them on — keep-alive under the existing "Serve on launch" setting, the hotkey works out of the box as Ctrl+Alt+H (Windows) with no setting yet to remap it.

Installing fresh

macOS — open the DMG, drag Claude Buddy to Applications, then double-click Install Hooks.command. Launch from Applications; nothing appears in the Dock and no window opens, which is correct — look in the menu bar.

Windows — run the setup. Per-user, so no UAC prompt. Leave the hook checkboxes ticked; tick "Wire hooks for Claude Code running inside WSL" too if you use it.

The hook step is not optional

Claude Buddy learns about your sessions from a hook that Claude Code, Codex, and Grok each run. Until it's wired in, the app starts and runs correctly and shows nothing at all. The installers offer to wire it up; let them. Existing settings are backed up first, and re-running repairs rather than duplicating.

Known limitations

Everything below is named because it was not measured, not because it is expected to fail.

• Cloud session orbs are unverified on Windows, and on the account they were built against, the feature draws exactly one orb — most rows in a real roster are local sessions registered for remote control, not cloud sessions, and that is the feature working correctly rather than a bug.
• Paired Codex/Grok mirroring and persona-over-the-wire have not had live cross-machine smoke testing. The release unit, integration and UI suites are green; a real paired macOS/Windows Codex or Grok session pending manual confirmation.
• The vibe code summary's round trip runs 6–7 seconds on the one machine it was measured on, and it does not fall back to the full response on failure — it says so in one sentence instead, by design.
• Whether the global hotkey actually fires on a real running app has not been confirmed on either platform from this pipeline; the registry, parsing and settings round-trip are unit-tested, but registering and receiving an OS-level hotkey needs a real window-server session no headless run has.
• Windows personas, Windows cloud orbs, and Windows crash keep-alive have not been run against a live install on that OS. CI runs the parse and UI tests on both legs.
• Local Network consent is lost on every upgrade, same as every prior release.
• Windows installers are unsigned — SmartScreen warns; choose More info → Run anyway. macOS builds are signed and notarized and open normally.

MIT licensed. Originally by @KawikaMiller.

Claude Buddy v0.5.3-beta

Orbs that look like the agent, and chats you can keep on screen. That is this release.

0.5.2 drew every local CLI as a mark in the corner and left the rest of the circle as two letters. Since then a project's CLAUDE.md can name the agent, put a face on it, and pick the voice it reads a turn in; an OpenClaw channel with two people in it is drawn as those people rather than as a room-name; a picture the gateway delivered actually shows up in the chat panel; and a panel you pin stays put instead of vanishing the moment you click away.

Still a beta. Personas were measured against real CLAUDE.md files on a Mac, including this repository's own. OpenClaw pictures and room orbs were measured against a live gateway. See Known limitations.

New: a persona from the markdown beside the work

An orb is normally named for whatever Claude Code decided the conversation was about, falling back to the folder. If a project's CLAUDE.md says what the agent working there is called, the orb wears that instead — its name, its picture, and the voice it reads a turn out in.

Nothing is turned on and no new file is introduced. It reads the Markdown that is already beside the work, and a project that says nothing about a persona is drawn exactly as it was before.

A bullet, YAML front matter, a bold field, a table row under a persona heading, and a marked fenced block (<!-- persona:start --> … <!-- persona:end -->) all carry the same three fields. A picture path is resolved against the file that named it and against the workspace root, so a generator that writes avatars/leota.png next to CLAUDE.md and one that writes it from the project root both work. Pictures are capped at 16 MiB.

Two Claude Code sessions in the same folder no longer share one persona between them: the orb is keyed by the agent, not by (cwd, source). A file at .claude/agents/<name>.md is not where a per-agent persona lives; profiles/<name>/ is.

New: an OpenClaw channel is the people in it

An agent's picture is its orb, and a channel's orb is everyone in it. An agent with an avatar set in OpenClaw wears it instead of its letters. A channel gets its own orb only once a second agent is in it — one agent talking in a channel is drawn as that agent, with the # badge. A second joining is what makes the room a thing, cut into a wedge per member, at most four, the four most recently active.

Only agents who still have an orb of their own get a wedge, so a quiet member stays in the conversation you open and drops off the faces. Heartbeat and cron sessions keep the shapes 0.4.3 gave them.

A workspace markdown file can also name a voice, a blend of Kokoro voices, and an optional speaking rate. When the gateway is on a paired peer, that already-resolved voice can travel over the peer link without sending the workspace files.

New: pictures in the OpenClaw chat panel

A picture the gateway delivered — live, from history, from a cron, or named as a trailing path on the caption — draws as a thumbnail in the panel rather than as a path you cannot click. A refusal from the gateway says why the picture did not load, instead of looking like nothing was sent.

New: pin a chat, and the header says where you are

The pin in the header keeps a chat open. A panel normally hides the moment you click anywhere else. Pin it and it stays where it is, its header becomes a title bar you can drag, and you can pin as many as you like. The next orb you click opens the ordinary come-and-go panel beside them, not on top of them. Size belongs to the agent, not the window: each one reopens at whatever you last dragged it to.

The header says which conversation this is, and where it is happening — the name and picture, then the session Claude Code calls this chat, the folder it is working in, and the machine it is running on. The machine is named always, and drawn in the session's own colour when it is not this machine.

A session with no terminal pane can still be reached: a delivered message is typed into Claude Code's own messaging socket rather than vanishing.

New: a vertical line, and Grok usage that stays honest

The arrange button gains a Vertical Line shape, next to the ones that were already there.

Settings → Grok Build, Keep Grok usage fresh automatically (off by default) starts and stops Grok in the background so the weekly credit figure is not whatever Monday's session wrote. macOS only; Windows no-ops rather than guessing at a pty API this app does not wrap.

Codex usage is now asked of Codex rather than waiting for a session to write a snapshot. Usage orbs also poll as often as the number is actually changing, and they breathe through a style instead of a fire-and-forget task that could leave a ring stuck.

Fixed

• An OpenClaw orb pinned "generating" forever by a stuck task, or by the gateway's sessions.changed chatter, goes idle when the work actually stopped.
• Settings no longer draws "Give each session a colour" twice.
• The chat header no longer repeats a gateway session's channel under its own chip.
• Hovering an orb no longer flickers the thought-bubble tooltip, including the account orb and the case where the tooltip overlapped the orb.
• A window that parked its conversation retires its orb. A room with one agent is not drawn as a room. A room orb no longer keeps faces for people who have gone idle.
• The default usage orb no longer inherits another account's numbers.
• OpenClaw starts its gateway connection before the screen-unlock wait, so a locked Mac mini still answers.
• Dialing an already-known peer fires the connected event, so a reconnect is not silent.
• A persona picture written as a code span, a blended voice, fenced YAML, a bold field, or a table row is actually read; a picture outside the workspace is refused rather than failing open.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.3-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.3-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.3-beta-win-x64-setup.exe

The ClaudeBuddySpeech-0.5.3-beta-*.zip assets are the optional high-quality voice engine. You do not download these yourself — the app fetches the right one when you turn the setting on. They are published here because that is where it looks.

The .NET runtime is bundled; nothing else is needed. SHA256SUMS.txt covers every file — verify with shasum -a 256 -c SHA256SUMS.txt on macOS or Get-FileHash <file> -Algorithm SHA256 on Windows.

Upgrading from 0.5.2-beta

macOS: replace the app in Applications. The signing identity is unchanged, so Automation permission and click-to-focus carry over.

Local Network permission does not. Replacing the app loses the grant, and paired machines plus an OpenClaw gateway start failing with No route to host. Approve it again in System Settings → Privacy & Security → Local Network. A headless Mac still cannot; pair from the machine with a screen and add the headless one by address.

Windows: run the new setup over the old one; it upgrades in place and leaves your hook configuration alone.

Personas are on as soon as a CLAUDE.md names one; there is no new switch. Grok auto-refresh is off by default.

Installing fresh

macOS — open the DMG, drag Claude Buddy to Applications, then double-click Install Hooks.command. Launch from Applications; nothing appears in the Dock and no window opens, which is correct — look in the menu bar.

Windows — run the setup. Per-user, so no UAC prompt. Leave the hook checkboxes ticked; tick "Wire hooks for Claude Code running inside WSL" too if you use it.

The hook step is not optional

Claude Buddy learns about your sessions from a hook that Claude Code, Codex, and Grok each run. Until it's wired in, the app starts and runs correctly and shows nothing at all. The installers offer to wire it up; let them. Existing settings are backed up first, and re-running repairs rather than duplicating.

Known limitations

Everything below is named because it was not measured, not because it is expected to fail.

• Windows personas, Windows OpenClaw pictures, and Windows Grok auto-refresh have not been run against a live CLI on that OS. CI runs the parse and UI tests on both legs. Grok auto-refresh is a documented no-op on Windows.
• Grok usage is as fresh as the last Grok session's log line, unless auto-refresh is on — and auto-refresh is macOS only.
• Codex usage is as fresh as Codex will answer, or as the last rollout token_count if it will not.
• Local Network consent is lost on every upgrade, same as 0.5.2.
• Windows installers are unsigned — SmartScreen warns; choose More info → Run anyway. macOS builds are signed and notarized and open normally.

MIT licensed. Originally by @KawikaMiller.

Claude Buddy v0.5.2-beta

Orbs now say which CLI they are. That is this release.

Claude, Codex, Grok and OpenClaw used to look the same from across the
room — the initials named the session, not the tool. Each local CLI orb
now wears a 22px disc in the bottom-left: terracotta spark, green star,
black X, lobster. Kind, heart and presence match that size, so an
OpenClaw channel is a lobster and an @, not a logo next to punctuation.

Still a beta. Codex usage is read off the last rollout on disk, the same
way Grok usage is read off its credits log: no login token, as fresh as
the last session. See Known limitations.

New: CLI marks on every local orb

A Claude orb, a Codex orb, a Grok orb and an OpenClaw orb are no longer
the same circle with different letters. Bottom-left:

• Claude — terracotta spark
• Codex — green star
• Grok — black X
• OpenClaw — lobster-red lobster

Remote-control orbs skip it: those are Claude Code on another machine,
and a spark there would look like a local Claude. OpenClaw keeps the
lobster even when it also has a kind badge — kind says cron / channel /
direct, the lobster says it is OpenClaw.

Usage orbs wear the same mark.

New: usage orbs for Codex (off by default)

Settings → Codex sessions now has the same usage-orb switch Claude
Code and Grok already had. Codex already writes the five-hour and weekly
windows onto every token_count event in the rollout; there is no
codex usage CLI and /status only exists inside a live session, so
the orb reads the newest snapshot off disk. Credits without a cap stay a
dotted inner ring rather than a share of a budget Codex did not send.

The figure is as fresh as the last Codex session on this machine —
Claude Buddy does not hold Codex's login token.

Fix: Grok usage orbs actually appear

0.5.1 shipped the Grok usage switch. Turning it on wrote the setting and
then asked a path that still looked only at the Claude Code flag: with
that off, every account orb closed; with that on, the Grok orb waited
out a five-minute Claude poll that has nothing to do with reading a log
file. Either way the switch said true and the screen stayed empty. The
Grok orb now draws when its own switch is on.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.2-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.2-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.2-beta-win-x64-setup.exe

The ClaudeBuddySpeech-0.5.2-beta-*.zip assets are the optional high-quality
voice engine. You do not download these yourself — the app fetches the
right one when you turn the setting on. They are published here because that is
where it looks.

The .NET runtime is bundled; nothing else is needed. SHA256SUMS.txt covers
every file — verify with shasum -a 256 -c SHA256SUMS.txt on macOS or
Get-FileHash <file> -Algorithm SHA256 on Windows.

Upgrading from 0.5.1-beta

macOS: replace the app in Applications. The signing identity is unchanged,
so Automation permission and click-to-focus carry over.

Local Network permission does not. Replacing the app loses the grant, and
paired machines plus an OpenClaw gateway start failing with No route to host. Approve it again in System Settings → Privacy & Security → Local
Network. A headless Mac still cannot; pair from the machine with a screen
and add the headless one by address.

Windows: run the new setup over the old one; it upgrades in place and
leaves your hook configuration alone.

Codex usage orbs are off by default. Turn them on under Settings → Codex
sessions if you want them.

Installing fresh

macOS — open the DMG, drag Claude Buddy to Applications, then double-click
Install Hooks.command. Launch from Applications; nothing appears in the
Dock and no window opens, which is correct — look in the menu bar.

Windows — run the setup. Per-user, so no UAC prompt. Leave the hook
checkboxes ticked; tick "Wire hooks for Claude Code running inside WSL"
too if you use it.

The hook step is not optional

Claude Buddy learns about your sessions from a hook that Claude Code, Codex,
and Grok each run. Until it's wired in, the app starts and runs correctly and
shows nothing at all. The installers offer to wire it up; let them.
Existing settings are backed up first, and re-running repairs rather than
duplicating.

Known limitations

Everything below is named because it was not measured, not because it is
expected to fail.

• Windows Codex usage and Windows Grok usage have not been run against a
  live CLI on that OS. CI runs the parse tests on both legs; a real
  ~/.codex / ~/.grok on Windows has not been read by the app.
• Codex usage is as fresh as the last rollout token_count. There is no
  public codex usage CLI, and this app does not hold Codex's token.
• Grok usage is as fresh as the last Grok session's log line, same as
  0.5.1.
• Local Network consent is lost on every upgrade, same as 0.5.1.
• Windows installers are unsigned — SmartScreen warns; choose More info →
  Run anyway. macOS builds are signed and notarized and open normally.

MIT licensed. Originally by @KawikaMiller.

Claude Buddy v0.5.1-beta

Grok Build sessions get orbs. That is this release.

0.5.0 shipped the pairing work and deleted the Remote Control relay. Grok
Build support was already written and sitting on an open PR against develop
(#135); it did not make that tag. This one is that PR, nothing else.

Still a beta. What follows was measured against grok 1.0.13 on a real Mac;
Windows Grok has not been run. See Known limitations.

New: Grok Build sessions as orbs

A live Grok session now shows up as an orb, labelled cli:grok, titled from
Grok's own summary.json — generated_title, and /rename when you have
used it. Click it and the chat panel is the real conversation, read off
updates.jsonl (ACP session/update envelopes), not a model's account of
it.

This used to almost work, and that was the bug. Grok's Claude Code
compatibility layer loads ~/.claude/settings.json, so Claude Buddy's Claude
Code hook was already firing for Grok sessions. The status file said
cli:claude, and auto-color appended a Claude Code agent-color record into
Grok's own transcript. The hook now treats GROK_SESSION_ID /
GROK_HOOK_EVENT as the source of truth, even when argv still says claude,
and it never writes into Grok's updates.jsonl.

Grok has no /color — /theme is TUI-wide. Auto-color derives a ring from
the working directory into the status file and stops there.

install-hooks.sh wires Grok when it finds ~/.grok or grok on PATH;
install-grok-hooks.sh is the per-CLI repair. Grok's ~/.grok/hooks/*.json
is always trusted — there is no Codex-style review step.

New: usage orbs for Grok (off by default)

Settings → Grok Build has the same four switches Claude Code and Codex
already had — show sessions, chat panel, reply, extra GROK_HOME accounts —
plus usage orbs.

A Grok usage orb wears the weekly credit window Grok already fetches.
There is no five-hour cap, so that ring is omitted rather than drawn at zero.
The figure is as fresh as the last Grok session on this machine: Claude Buddy
reads the billing: fetched credits config line out of
$GROK_HOME/logs/unified.jsonl and does not hold Grok's login token.

Which file do I want

Platform	Download
macOS, Apple silicon (M1 and later)	ClaudeBuddy-0.5.1-beta-osx-arm64.dmg
macOS, Intel	ClaudeBuddy-0.5.1-beta-osx-x64.dmg
Windows 10/11, 64-bit	ClaudeBuddy-0.5.1-beta-win-x64-setup.exe

The ClaudeBuddySpeech-0.5.1-beta-*.zip assets are the optional high-quality
voice engine. You do not download these yourself — the app fetches the
right one when you turn the setting on. They are published here because that is
where it looks.

The .NET runtime is bundled; nothing else is needed. SHA256SUMS.txt covers
every file — verify with shasum -a 256 -c SHA256SUMS.txt on macOS or
Get-FileHash <file> -Algorithm SHA256 on Windows.

Upgrading from 0.5.0-beta

macOS: replace the app in Applications. The signing identity is unchanged,
so Automation permission and click-to-focus carry over.

Local Network permission does not. Same CDHash rule as 0.5.0: replacing
the app loses the grant, and paired machines plus an OpenClaw gateway start
failing with No route to host. Approve it again in System Settings →
Privacy & Security → Local Network. A headless Mac still cannot; pair from
the machine with a screen and add the headless one by address.

Windows: run the new setup over the old one; it upgrades in place and
leaves your hook configuration alone.

Then run the hook installer so Grok is wired — install-hooks.sh inside the
app, or the Install Hooks.command on the DMG. Restart any open sessions,
Grok included. Hooks are read once at session start.

A Grok session that already had an orb labelled as Claude Code will correct
itself on the next hook fire after that restart.

Installing fresh

macOS — open the DMG, drag Claude Buddy to Applications, then double-click
Install Hooks.command. Launch from Applications; nothing appears in the
Dock and no window opens, which is correct — look in the menu bar.

Windows — run the setup. Per-user, so no UAC prompt. Leave the hook
checkboxes ticked; tick "Wire hooks for Claude Code running inside WSL"
too if you use it.

The hook step is not optional

Claude Buddy learns about your sessions from a hook that Claude Code, Codex,
and Grok each run. Until it's wired in, the app starts and runs correctly and
shows nothing at all. The installers offer to wire it up; let them.
Existing settings are backed up first, and re-running repairs rather than
duplicating.

Known limitations

Everything below is named because it was not measured, not because it is
expected to fail.

• Windows Grok, WSL Grok, and a second GROK_HOME account have not been
  run. The PowerShell installer and hook path exist; CI runs the Windows
  hook tests; a real grok on Windows has not.
• A real Grok permission-prompt pane has not been captured, so dialog
  buttons in the chat panel are assumed rather than verified. PostToolUse is
  not wired until that is measured.
• Whether spawn_subagent is a new grok pid (team arrows) or
  in-process is unknown. An in-process spawn must not be hidden by the
  superseded-by-pid rule; that path is untested against a live spawn.
• The exact JSON key /rename writes when title_is_manual is true has
  not been seen. The hook prefers title in that case, then
  generated_title.
• Usage orbs are as fresh as the last Grok session's log line. There is
  no public grok usage CLI, and this app does not hold Grok's token, so
  there is no five-minute poll the way Claude Code usage orbs have.
• Local Network consent is lost on every upgrade, same as 0.5.0.
• Windows installers are unsigned — SmartScreen warns; choose More info →
  Run anyway. macOS builds are signed and notarized and open normally.

docs/grok-findings.md is the record of what was actually read off grok
1.0.13 versus assumed.

MIT licensed. Originally by @KawikaMiller.