A desktop companion that lets you monitor your AI coding agent. See when the agent is done, when it needs input, and how much context has been used without having to stare at your terminal. Also, it's cute.
- Node.js 18+
- Claude Code CLI and/or Codex CLI
npm install -g agent-paperclipAfter installing, configure the Claude Code hooks:
agent-paperclip setupThen launch the app:
agent-paperclipTo stop: run agent-paperclip stop, use Cmd+Q, or quit from the dock.
Codex support is automatic -- if ~/.codex/ exists, a background watcher picks up Codex sessions with no extra setup.
-
Clone and install:
git clone https://github.com/fredruss/agent-paperclip cd agent-paperclip npm installThis installs dependencies and prompts to configure Claude Code hooks. Type
yto allow. -
Run the app:
npm run dev
The pet window will appear and float on top of other windows. It automatically updates based on what the agent is doing:
- Thinking - The agent is reasoning or responding
- Reading - Reading files or searching code
- Working - Writing, editing, or running commands
- Waiting - Needs your permission or has a question
- Idle - Waiting for input
- Done - Finished a task
- Error - Something went wrong
The pet also displays the context window usage (input + cache tokens from the latest API call).
When the agent is idle, a small badge like Claude: 42% · 3h shows how much of the 5-hour session window is used and how long until it resets. A few notes:
- Works with Claude Code and Codex; the label reflects whichever agent most recently reported usage. Codex support has only been tested on macOS.
- Paid plans only — free-tier sessions don't expose this data, and values populate after the first API response in a session.
- Claude data comes from a statusLine script installed by
agent-paperclip setup(any pre-existing statusLine is preserved). The badge only appears when the pet is idle.
It can also play a sound when the agent needs input (Waiting) or finishes (Done). This can be turned off from the pet's menu.
3 sticker packs available.
- Drag - Click and drag the pet to move it around your screen
- Right-click - Open the pet menu to change sticker pack or toggle sound notifications
The companion supports two agents via different mechanisms:
Claude Code uses the hook system to receive real-time events:
Claude Code --[hooks]--> status-reporter.js --> status.json <--[watching]-- Desktop Pet (Electron)
Codex CLI is monitored passively by tailing its session rollout files:
Codex CLI --> ~/.codex/sessions/*.jsonl <--[tailing]-- codex-watcher --> status.json <--[watching]-- Desktop Pet
Both write to the same ~/.agent-paperclip/status.json, so the pet reflects whichever agent is currently active.
The companion displays status information from ~/.agent-paperclip/status.json.
What IS captured in status.json:
- Tool names - Read, Write, Bash, Grep, etc.
- Filenames - Names of files being read, written, or edited (e.g.,
Reading index.ts...) - Command names - First word of bash commands (e.g.,
Running npm...) - Search patterns - Grep patterns, truncated to 20 characters (e.g.,
Searching for "pattern"...) - Thinking snippets - Brief excerpts of agent reasoning, truncated to ~40 characters
- Token counts - Current context window usage
What is NOT captured:
- Agent responses to you (only internal "thinking" blocks are read)
- Your prompts or questions
- File contents or code
- Full bash commands (only the first word)
All data stays local on your machine and is never sent anywhere.
For Claude Code, token counts and thinking snippets are extracted from the transcript file (~/.claude/projects/.../session.jsonl), not from hook events. For Codex, they come from the session rollout JSONL files in ~/.codex/sessions/.
To build distributable installers for your platform:
cd app
npm run dist # Build for current platform
npm run dist:mac # macOS .dmg
npm run dist:win # Windows .exe
npm run dist:linux # Linux .AppImageOutput goes to app/dist/.
Note: macOS builds will show a security warning unless code-signed with an Apple Developer certificate.
Check that the hooks are configured in ~/.claude/settings.json:
cat ~/.claude/settings.json | grep agent-paperclipIf hooks are missing, run agent-paperclip setup to configure them.
Make sure ~/.codex/ exists (created automatically when Codex CLI is first used). The companion will detect it on launch and start watching for sessions.
On macOS, you may need to allow the app in System Preferences > Security & Privacy.
MIT