Clawde reads your Claude Code sessions and draws them on your screen. That is a sensitive position to sit in, so here is exactly what it touches.
Reads:
- The hook payload Claude Code sends on stdin.
~/.claude/sessions/*.json— to resolve a session's display name and pid.- The tail of the session transcript (last 400 KB) — to build the summary
bullets. Only on
done; thebusypath skips it entirely. psoutput for the session's pid and its ancestors — to find the tty and which terminal app owns it.
Writes:
~/.claude/clawde/inbox.jsonl— one JSON line per event, mode0600.~/.claude/clawde/history.jsonl— finished turns, for the stats.- Hammerspoon's preferences, under the
clawde.statekey.
That is the whole list. It does not read your code, your shell history, your keychain, or any file outside the paths above.
There is none. No HTTP client, no sockets, no telemetry, no update check, no
analytics. grep -rn "hs.http\|socket\|curl\|https://" hammerspoon/ hooks/
returns nothing.
Your session titles, prompts and summaries never leave the machine.
None required.
Hammerspoon will ask for Accessibility on first launch because Hammerspoon asks
generically at startup — the pet does not use it. Dragging is implemented by
polling the mouse rather than with hs.eventtap, precisely so that it works
with the permission denied. Dismiss the prompt and everything still works.
Hammerspoon can expose a bridge (hs.allowAppleScript(true)) that lets any
process on your Mac execute arbitrary Lua inside Hammerspoon — which means
running code as you. That is a real privilege-escalation surface.
The installer never enables it, and the init.lua it ships has the line
commented out with an explanation. The pet does not need it: every control is in
its menu, and Hammerspoon's own Console runs the same debug commands.
Note that the pet calls out to AppleScript (hs.osascript) to select a
terminal tab. That is the opposite direction and does not require the bridge.
Session text can quote anything you pasted into Claude, including secrets. Every
string that reaches the inbox — titles, prompts, summary bullets, question text
and options — is run through a redactor first. It covers OpenAI/Anthropic keys,
GitHub tokens and PATs, Slack tokens, AWS access key ids, Google API keys, JWTs,
PEM private key headers, key=/secret=/password=/token= assignments, and
long opaque base64-ish blobs.
Redaction happens before the line is written, so a secret never lands on disk, not even briefly.
This is a safety net, not a guarantee. A credential in an unusual format can get
through. Treat ~/.claude/clawde/ as sensitive.
The tty is the only value interpolated into an AppleScript string. It is matched
against ^/dev/tty[a-zA-Z0-9]+$ first and dropped if it doesn't fit, so nothing
from a session name or a path can smuggle in script of its own.
Paths handed to open are quoted with %q and checked for existence first.
- Installs Hammerspoon via Homebrew, if missing.
- Copies the pet to
~/.hammerspoon/clawde/and the hook to~/.claude/hooks/clawde.sh. - Appends
clawde = require("clawde")to~/.hammerspoon/init.lua, creating it if absent. - Adds five hook entries to
~/.claude/settings.json, backing it up first and appending to existing groups rather than replacing them. - Retires the original claudepet's hook entries, unless
--keep-claudepet. - Turns on Hammerspoon's launch-at-login, hides its Dock icon, shows its menu bar icon — once, on first run, and only once.
./uninstall.sh reverses all of it, and only ever removes hook entries whose
command it can see is its own.
UserPromptSubmit and Stop fire on every single turn, so the hook is on your
hot path. It is written to never block and never fail one:
- All work happens in a Python block whose stderr is discarded.
- Every filesystem and
pscall is wrapped, with timeouts on subprocesses. - The script ends in
exit 0unconditionally. - The
busypath deliberately skips the transcript read, because it runs before your turn starts.
If it breaks, your session carries on as if it weren't there.
Open an issue, or if it's sensitive, say so in the issue without the details and we'll take it from there.