Claude the Cat Agent 🐱

Little cats that walk along your macOS dock. Click one to chat with a real Claude Code session — full tools, MCP servers, skills, and subagents — using your existing Claude Code login. No API key required.

When you start a Claude Code session in any terminal, a cat appears automatically. Click it to talk to that session.

A menu-bar app for macOS. Built with AppKit + SwiftUI, talking to the claude CLI over its stream-json interface.

---

What the cats mean

Badge	Cat	Clicking it opens…
🐱	Session cat (e.g. Bruce, Jazz)	a fresh, plain Claude Code session. Each has its own editable personality.
🤖	Subagent cat	a session bound to one subagent (--agent), auto-discovered from your .claude/agents/.
📁	Live-session cat	resumes the exact Claude Code session a terminal just started (named after its folder).

Each cat carries a small label so you can tell them apart at a glance.

Cats react to their session (live 📁 cats): when the session is working, the cat stops and a thought cloud appears over its head; when the session needs your attention (a permission prompt or idle-waiting), its tail wags faster; when it finishes, it walks again. This needs the activity hooks — if you installed hooks before this feature existed, re-run menu → Install Session Hooks… once.

How it works

Two channels, both feeding the same cats:

1. Trigger (hooks). A loopback HTTP listener runs inside the app on 127.0.0.1:8787. SessionStart / SessionEnd hooks in ~/.claude/settings.json POST their event there, so a cat appears when a session starts and retires when it ends. Install them from the menu bar → Install Session Hooks… (or the first-run prompt).
2. Discovery (disk scan). Hooks only fire for sessions that start while the app is running. To also surface sessions that are already open, the app scans ~/.claude/projects/*/*.jsonl on launch and every 60s (or on demand via menu → Scan Active Sessions). The most-recent transcript per project that was modified in the last 30 minutes becomes a cat — session id from the filename, cwd read from inside the transcript. Cats whose session goes quiet age out automatically.
3. Chat (stream-json). Clicking a cat launches a long-lived claude -p --input-format stream-json --output-format stream-json process. Your messages stream in; text deltas and 🔧 tool-use events stream back. Live-session cats add --resume <id> --fork-session; subagent cats add --agent <name>; session cats layer their personality via --append-system-prompt.

 terminal: `claude` ──SessionStart hook──▶ :8787 listener ──▶ 🐱 cat appears
                                                                  │ click
                                                                  ▼
                                              claude -p (stream-json) ⇄ chat

Requirements

• macOS 13 (Ventura) or later
• Claude Code installed and logged in (claude on your PATH)
• Xcode 15+ to build from source

Install

Option A — download a build

Grab the latest ClaudeTheCatAgent.app.zip from the Releases page, unzip, and move it to /Applications.

Because the app isn't notarized, the first launch is gated by Gatekeeper: right-click the app → Open → Open. After that it launches normally.

Option B — build from source

git clone https://github.com/kaarthi19/claudethecat.git
cd claudethecat
xcodebuild -project LilAgents.xcodeproj -scheme LilAgents -configuration Release build
open ~/Library/Developer/Xcode/DerivedData/LilAgents-*/Build/Products/Release/"Claude the Cat Agent.app"

Or just open LilAgents.xcodeproj in Xcode and hit Run.

Using it

1. Launch the app — it lives in the menu bar (🐱), not the Dock.
2. On first run, accept Install Session Hooks (or do it later from the menu).
3. Start a Claude Code session in any terminal → a 📁 cat appears.
4. Click any cat to chat. Ask it to run a command to see the tools work.

Settings (menu bar → Settings…)

• Add / remove cats, rename them, set size.
• Connect to: a plain Claude Code session or a named Subagent.
• Personality: extra system prompt for session cats (hidden for subagents, which bring their own).
• Drop a transparent .mov (HEVC with alpha) into the Videos folder and reference it by filename to give a cat custom artwork. Without one, a lightweight built-in cat is drawn.

Notes

• Memory: built-in (drawn) cats cost ≈1 MB each; the app idles around ~230 MB (mostly AppKit/SwiftUI framework baseline). Custom videos are decoded once and shared across all cats, so video memory stays flat regardless of cat count. Live-session cats are capped at 12.
• Each open chat is its own claude process (separate context, and its own memory — typically 100 MB+). Close chats you aren't using.
• The listener is loopback-only and unauthenticated — fine for a local single-user tool. Anything running on your Mac could POST to port 8787.

Project layout

LilAgents/
├─ AppDelegate.swift          menu bar, onboarding, wiring
├─ AgentManager.swift         spawns/retires cats; subagent discovery
├─ DockPositioner.swift       dock-edge detection + walk bounds
├─ Models/AgentConfig.swift   cat model: kind, persistence, discovery
├─ Views/
│  ├─ AgentWindowController.swift  the walking window + sprite cache
│  ├─ ChatView.swift              chat UI + session view-model
│  ├─ SettingsView.swift          settings + per-cat editor
│  └─ FallbackCatView.swift       drawn cat when no video is set
└─ Services/
   ├─ ClaudeCodeSession.swift  the `claude` CLI driver (stream-json)
   ├─ HookListener.swift       :8787 listener + hook installer
   └─ SessionScanner.swift     discovers already-running sessions from disk

License

MIT © 2026 Kaarthigeswaran A Gnapathy