A privacy-first pixel desktop companion for Claude Code and Codex.
Pixel Agent Buddy turns native Claude Code and Codex lifecycle hooks into a small ambient signal on your desktop. It shows whether an agent is thinking, working, waiting for approval, finished, failed, or sleeping—without reading your prompt, code, transcript, assistant message, or tool payload.
- Privacy is the product — only a small, documented metadata whitelist leaves the hook process.
- Native hooks only — no transcript scraping, log polling, external gateway, or hidden fallback.
- Fail-open observation — it never takes over Allow/Deny; the native CLI remains authoritative.
- Small on purpose — no chat, memory, RPG, leaderboard, dashboard, or remote control.
- Two original pixel identities — Claude Code gets a warm crab; Codex gets a terminal robot crab.
- Safe coexistence — installation preserves unrelated hooks and rolls back on failure.
| State | Meaning |
|---|---|
| Idle | Ready for a new task |
| Thinking | Reading context or planning |
| Working | Running tools or changing files |
| Approval | Waiting for native CLI permission |
| Success | The task finished |
| Error | A tool or turn failed |
| Sleeping | No active Claude Code or Codex session |
Download the latest Windows installer or portable build from GitHub Releases. Downloaded builds include their own Hook runner and do not require a separate Node.js installation. The app offers to connect the supported Agent CLIs detected on first launch.
The first-run setup shows the detected CLI versions, Hook health, runner mode, and local runtime status in one place. Install or repair the detected Hooks, then send a test state before closing the guide. The same diagnostics screen remains available from the pet or tray menu.
Requirements: Windows 10/11, Node.js 20+ for source development, and Claude Code and/or a Codex CLI version with lifecycle hooks.
git clone https://github.com/44-99/pixel-agent-buddy.git
cd pixel-agent-buddy
npm install
npm run install:hooks
npm startInstall only one adapter when needed:
npm run install:claude
npm run install:codexCheck the local installation:
npm run doctorRemove only the hooks managed by Pixel Agent Buddy:
npm run uninstall:hooksDrag the pet with the left mouse button. Right-click it for the small operational menu: setup and diagnostics, Hook status and repair, startup behavior, hide, and quit. Animation states are driven by Agent events; the diagnostics screen can send an explicit local test state.
Hooks may send only:
- agent type;
- session, parent-session, and subagent identifiers;
- lifecycle event and normalized display state;
- current working directory and its basename;
- tool name;
- local timestamp.
Hooks never send prompts, code, tool_input, tool_response, transcript content, assistant messages, or permission decisions. Transport stays on authenticated 127.0.0.1. See PRIVACY.md for the complete contract.
There is no automatic update request. The app contacts the public GitHub Releases API only after the user presses Check for updates.
Claude Code adapter ─┐
├─> sanitized event hook
Codex adapter ───────┘ │
├─> authenticated localhost HTTP
├─> multi-session activity arbitration
└─> Electron presentation → pixel companion
The installer validates every target configuration before writing anything. Configuration changes use backups and a rollback transaction, while unrelated hook entries remain untouched.
See Agent compatibility for verified CLI versions, provider-specific event coverage, and the Codex Hook trust step.
npm test
npm run build
npm run generate:assets
npm run preview:assets
npm run preview:setupThe two transparent PNG characters are generated deterministically from project-owned source shapes. They require no image API or third-party art.
Pixel Agent Buddy deliberately focuses on ambient status for Claude Code and Codex. Additional agent adapters will be considered only when users ask for them and the provider exposes a stable lifecycle seam.
See CONTRIBUTING.md before proposing a new adapter or product-scope expansion.