Skip to content

Security: svaka2000/clawde

Security

SECURITY.md

Security & privacy

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.

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; the busy path skips it entirely.
  • ps output 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, mode 0600.
  • ~/.claude/clawde/history.jsonl — finished turns, for the stats.
  • Hammerspoon's preferences, under the clawde.state key.

That is the whole list. It does not read your code, your shell history, your keychain, or any file outside the paths above.

Network

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.

macOS permissions

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.

The AppleScript bridge is off by default

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.

Credential redaction

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.

Command injection

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.

What the installer changes

  • 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.

The hook runs on every turn

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 ps call is wrapped, with timeouts on subprocesses.
  • The script ends in exit 0 unconditionally.
  • The busy path 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.

Reporting something

Open an issue, or if it's sensitive, say so in the issue without the details and we'll take it from there.

There aren't any published security advisories