Pixel Agent Buddy

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.

Why Pixel Agent Buddy?

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.

States

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

Quick start

Download

Install Node.js 20+ first, then download the latest Windows installer or portable build from GitHub Releases. The app offers to install its local hooks on first launch.

Run from source

Requirements: Windows 10/11, Node.js 20+, Claude Code 2.1+ and/or a Codex CLI version with hooks.

git clone https://github.com/44-99/pixel-agent-buddy.git
cd pixel-agent-buddy
npm install
npm run install:hooks
npm start

Install only one adapter when needed:

npm run install:claude
npm run install:codex

Check the local installation:

npm run doctor

Remove only the hooks managed by Pixel Agent Buddy:

npm run uninstall:hooks

Privacy contract

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.

How it works

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.

Development

npm test
npm run build
npm run generate:assets
npm run preview:assets

The two transparent PNG characters are generated deterministically from project-owned source shapes. They require no image API or third-party art.

Project scope

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.

pixel-agent-buddy