Puck for macOS 0.2.1

A fix for the pose preview in Settings. Everything else is 0.2.0.

The preview showed a pet nobody has

Settings → Poses draws each pose so you can turn artwork that came out
wrong the right way up. It and the pet composed the same two parts in
opposite orders: the renderer turns the drawing and flips the result, the
preview flipped it and turned the result.

Rotating a mirrored sprite turns it the other way, so every pose that is
mirrored and turned at once — a pet climbing the wall on its left, and
any pose given both a horizontal correction and a rotation — was drawn one
way in the window and the other way on the desktop. Which made the preview
worse than useless: it is there to be looked at while correcting artwork,
and it was showing something else.

The order now lives in one place both of them call, and a test fails if the
preview's two lines are ever swapped back.

Install

Download Puck-0.2.1.dmg below and drag Puck into Applications. macOS 14 or
newer. The chat window is inside the app and comes up with it; there is
nothing else to move.

The image is signed ad-hoc rather than with a Developer ID, so the first launch
is refused as coming from an unidentified developer: right-click the app →
Open → Open. Puck then asks for Accessibility, and for the microphone,
speech recognition and screen recording as you use the features that need them.

Building from source instead is sh pet-app/scripts/install.sh — see the README.

New in 0.2.0, if you are coming from 0.1.1: conversations kept between
launches, shells the agent can leave running, runs on a schedule, a change
review before you keep what an agent did, and reading and typing into other
apps. See the 0.2.0 notes.

Puck for macOS 0.2.0

Work that survives being quit, and an agent that can be left running.

The window remembers

Conversations are kept between launches. Workspaces survived a restart and
the talking in them did not, which made the window a scratchpad rather than
somewhere work lives. They are in chats.json, beside workspaces.json.

It opens big enough for what is in it. Explorer, editor, transcript and
island at once, in a window that used to be sized for a chat box.

A pasted file no longer buries the conversation. A long message shows its
first lines with the count and the size, and opens as a .txt. Tool calls draw
one line each — an agent that used twenty tools in a turn was burying the part
anybody reads.

The agent

Shells that outlive the call that started them. run_shell waits for a
command to exit, so the one thing it could not do was the thing that never
does: a dev server, a watcher, a build left running. Four tools instead —
start, read, send, stop.

Runs on a schedule. "매일 아침 CI 확인해서 깨졌으면 알려줘" is the obvious
thing to ask a pet living on your desktop, and there was no way to say it.
Every so many minutes, once a day, or on the weekdays you pick. Only while
Puck is up; one whose time passed while it was shut runs once when it comes
back, not once per hour it missed.

A change review before you keep what it did. ⇧⌘R shows the working tree
file by file with the hunks, and puts one back if you would rather it had not.

Reading and typing into other apps. app_snapshot gives the agent the
whole of a window as an outline — the question you can only ask before you
know what to look for — and with it typing, key chords and scrolling. Text
goes in as unicode, so a Korean layout types what was asked for. Typing and
pressing ask for approval; reading and scrolling do not.

The pet

It stood still through everything the agent did. It now takes a posture that
matches the tool, speaks up when a run finishes behind another window, and
comes to the pointer when a run has stopped to ask for approval. A character
package can replace what it says, keyed by the moment. Off by an option, for
anyone who wants it quiet.

Fixed

• The pet no longer shrinks. Two faults, both of which read as "it gets
  smaller every time I alt-tab": the size was remembered as a drawn height
  rather than a fraction, and a trip ordered into the tank was thrown away if
  the pet was interrupted on the way.
• A folded island stays in the menu strip instead of cutting a bezel
  across the window and pushing the transcript down.
• A coding agent is no longer killed three minutes into a ten-minute turn.
  The clock now measures how long it has said nothing, not how long it has
  worked.
• A CLI whose login expired says so, and names the command that signs it
  back in, instead of "execution failed".
• No more EMFILE watching a project of any size: the app raises the
  descriptor limit launchd hands it.
• An agent that dies explaining itself is heard. Its last words could be
  lost to a race with its own exit.

Install

Download Puck-0.2.0.dmg below and drag Puck into Applications. macOS 14 or
newer. The chat window is inside the app and comes up with it; there is
nothing else to move.

The image is signed ad-hoc rather than with a Developer ID, so the first launch
is refused as coming from an unidentified developer: right-click the app →
Open → Open. Puck then asks for Accessibility, and for the microphone,
speech recognition and screen recording as you use the features that need them.

Building from source instead is sh pet-app/scripts/install.sh — see the README.

Puck for macOS 0.1.1

The notch panel, and one app instead of two.

The notch

Puck draws a notch panel at the top of the screen. Point at it and it opens;
move away and it shuts.

It shows what the whole machine is playing — not only Music and Spotify,
but anything, a browser tab included. Cover art, title, artist, the playhead,
transport controls, and the line being sung when the song is in
LRCLIB.

Shut, it still says something. While a song is playing the notch reaches
out to either side: a thumbnail on one side, a small level meter on the other.

A display without a camera housing gets one anyway, drawn in the menu bar,
so this is not a MacBook-only feature. The pet is given real housings only —
it never ducks around a drawn one.

Off by default until now; on from this release. The switch is in Settings.

One app

The image now ships one app. PuckClient rides inside Puck.app rather than
beside it — two bundles in Applications meant searching for "Puck" offered two
things to launch, one of which is a window the other one opens for you.

Install

Download Puck-0.1.1.dmg below and drag Puck into Applications. macOS 14 or
newer. The chat window is inside the app and comes up with it; there is
nothing else to move.

The image is signed ad-hoc rather than with a Developer ID, so the first launch
is refused as coming from an unidentified developer: right-click the app →
Open → Open. Puck then asks for Accessibility, and for the microphone,
speech recognition and screen recording as you use the features that need them.

Building from source instead is sh pet-app/scripts/install.sh — see the README.

Credits

Now-playing information is read through
mediaremote-adapter (BSD
3-Clause), bundled and run under /usr/bin/perl. Lyrics come from LRCLIB.

Puck for macOS 0.1.0

The first release of Puck for macOS — a desktop pet that is also an AI agent.

Two apps that ship together and talk to each other over a local socket:

• Puck — the pet: an always-on-top character that walks your screen, climbs
  your windows, points at things, listens for voice, and drives the Mac
  (run_shell, run_applescript, click/find UI elements, launch apps).
• PuckClient — its window: chat, workspaces, git status, a native SwiftUI
  code editor, and a terminal pane.

Install

Download Puck-0.1.0.dmg below and drag both apps into Applications. macOS 14
or newer.

The image is signed ad-hoc rather than with a Developer ID, so the first launch
is refused as coming from an unidentified developer: right-click the app →
Open → Open, once per app. Puck then asks for Accessibility, and for the
microphone, speech recognition and screen recording as you use the features that
need them.

Building from source instead is sh pet-app/scripts/install.sh — see the README.

Connect an AI

Chat talks to the Anthropic or OpenAI API directly. The code_editor tool runs
a vendored ACP agent under node, which needs its vendor's CLI (claude or
codex). Keys go in ~/Library/Application Support/Puck/.env.

Make it your own

An avatar is a folder with a manifest.json and one PNG per clip — one drawing
is already a working character. Drop a seabed.png into Tank/ to change what
the island is filled with. The full format is in the
README.

---

macOS용 Puck의 첫 릴리즈입니다. 아래 Puck-0.1.0.dmg를 받아 두 앱을 응용 프로그램
폴더에 넣으세요 (macOS 14 이상). ad-hoc 서명이라 첫 실행은 "확인되지 않은 개발자"로
거부됩니다 — 앱을 우클릭 → 열기 → 열기를 앱마다 한 번씩. 한국어 안내는
README.ko.md에
있습니다.