lockpaw: Instructions file for Claude Code

Lockpaw

macOS menu bar screen guard. Lock/unlock with a hotkey; the covered screen glows when your AI agent (Claude Code / Codex / Gemini) needs you. Dog or cat mascot.

Quick reference

• App name: Lockpaw
• Bundle ID: com.eriknielsen.lockpaw
• URL scheme: lockpaw://
• Website: getlockpaw.com (hosted on Inleed, deployed via FTP from sorkila/lockpaw-web)
• Repo: [email protected]:sorkila/lockpaw.git
• Requires: macOS 14+, Xcode 16+, XcodeGen
• Dependencies: Sparkle (SPM, auto-updates with EdDSA signing)
• Current version: 1.7.0
• Size: ~14 MB DMG download, ~17 MB installed (2.8 MB of that is Sparkle; 2.4 MB is the 1.6 mascot art) — keep README/site/marketing claims in sync with the actual DMG when this changes

Build

xcodegen generate
xcodebuild -project Lockpaw.xcodeproj -scheme Lockpaw -configuration Debug build

After each rebuild, reset TCC (binary signature changes invalidate Accessibility permission):

tccutil reset Accessibility com.eriknielsen.lockpaw

Test

xcodebuild -project Lockpaw.xcodeproj -scheme Lockpaw -configuration Debug test

338 unit tests covering LockState transitions, Constants formatting, HotkeyConfig conflict detection/auth-required unlock preference/hotkey matching, SleepPreventer state handling, Mascot resolution (incl. the hidden and custom cases), CustomMascot store (atomic install, downsampling, rejection leaves the old image intact, cached hasImage), PingDecision agent-ping branching, AgentPing payload decoding (hook event → kind, agent/project names, CLI forwarding), AgentHookConfig hook merging (in-place upgrade, matcher, foreign hooks untouched), AgentConnection (which agents already have the hook, read from their configs), FadeToBlack preference resolution (checkbox × delay), every branch of the PresentationLogic fade-to-black reducer, TerminationPolicy (quit refused unless .unlocked), OverlayPolicy (no overlay is ever transparent to the pointer; only the primary takes key, except the clicked screen for one Mirror-mode auth attempt), LockdownPolicy (Space-switching gesture types incl. the Dock's control stream are swallowed, also while the auth dialog has the keyboard), ScreenLayout (overlays rebuild only on real display changes), PingGate (each session announced once per kind per lock), PingIntake (every ping recorded, only the announcement gated), AgentPingQueue (one row per session, the glow speaks for the most urgent outstanding ping, urgent-first rows, a row names who and not what), LidSleepPolicy/SystemLockPolicy (lid-closed cutouts; a forged macOS-unlock notification can't unlock), the helper's code-signing requirement, WebhookRelay (exactly what leaves the Mac) and its throttle, SupporterLicence/SupportAsk (the once-ever card's gates, the yearly menu line)/SeasonalSkin, the Codex TOML placement, that every bundled mascot asset ships, PassiveAuthPolicy (when the Touch ID sensor may be armed × how each LAError ending is scored, including that no ending can spend an unlock attempt), InputBlockPolicy (a held hotkey toggles once; the deferred keyboard-blocker start only runs while still locked), PasswordEntryPolicy (the kiosk options that hold the keyboard while the lock-screen password field is open, its idle close, and the Command-key filter), DesktopWallpaper (per-screen lookup in the private wallpaper store — this Space and display before global, leftovers skipped — and that malformed or older stores fail safe to the still), WallpaperPlaybackPolicy (when the shared Aerial player runs), and ImageDownsampling (wallpaper stills decoded at their fill size).