Agent Paperclip

Agent Paperclip

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.

Installation

Prerequisites

• Node.js 18+
• Claude Code CLI and/or Codex CLI

Option 1: npm (recommended)

npm install -g agent-paperclip

After installing, configure the Claude Code hooks:

agent-paperclip setup

Then launch the app:

agent-paperclip

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

Option 2: From source

1. Clone and install:

   git clone https://github.com/fredruss/agent-paperclip
   cd agent-paperclip
   npm install

   This installs dependencies and prompts to configure Claude Code hooks. Type `y` to allow.

2. Run the app:

   npm run dev

Usage

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

Usage badge

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;