pixel-agents README

The project's README from github.com/pixel-agents-hq/pixel-agents. As one markdown file: README.md.

Pixel Agents

The most playful way to orchestrate your agents

version marketplaces npm downloads stars license discord

🛒 VS Code Marketplace • 🛒 Open VSX • 📦 npm • 👾 Discord • 💬 Discussions • 🤝 Contributing • 📋 Changelog

Pixel Agents turns the AI coding agents running in your terminals into animated pixel-art characters working in a tiny office. They walk to their desks, sit down, type when they're editing files, read when they're searching, and flag you visually when they're stuck waiting for input.

It ships in two forms from the same codebase:

The architecture is fully agent-agnostic and editor-agnostic: a typed HookProvider interface defines the integration boundary so adding a new AI tool is a single subdirectory of code. Claude Code is the reference implementation today; Codex, Gemini, Cursor, and others are on the roadmap.

Pixel Agents screenshot

Features

Pixel Agents characters

Where This Is Going

The vision is: play a game, build a product. Two goals follow from it: to build a familiar, intuitive interface for running and orchestrating a lot of agents; and to make the hours you spend doing it feel less like administration and more like play.

Roughly three stages get there:

  1. Everywhere, with everything. Today it's Claude Code in VS Code or the browser. It should be whatever agent you run, wherever you work. A new CLI is a subdirectory, not a rewrite — this is where help is most useful right now.
  2. Actually a game. Health bars for rate limits and token budgets. Scores for whatever you care about. Furniture that does things. Offices you open like save files, one per project.
  3. Expand the orchestration frontier. Orchestrator characters. Form a team by dragging a box around them. Hand work between agents. Point them at a board and let them pick up tasks themselves.

Most of this is still ahead. See Issues and Discussions for what's open, and CONTRIBUTING.md to jump in.

Requirements

Getting Started

VS Code extension

  1. Install Pixel Agents from the VS Code Marketplace or Open VSX.
  2. Open the Pixel Agents panel beside the terminal.
  3. Click + Agent to launch Claude Code. In a multi-root workspace, select the folder first.

To use Claude with --dangerously-skip-permissions, hover over + Agent to find the Skip permissions mode button. Only use this when you accept the security implications.

Pixel Agents also detects Claude sessions started outside the extension. Turn on Settings → Watch All Sessions to include sessions from other workspaces.

Standalone CLI

Run Pixel Agents from the workspace whose Claude sessions you want to see:

cd /path/to/your/project
npx pixel-agents

The CLI chooses a free local port and prints the URL. Standalone does not launch Claude for you; start Claude Code in a terminal for the same workspace. To install the command globally instead:

npm install --global pixel-agents
pixel-agents

Use a fixed address or port when needed:

pixel-agents --port 3100
pixel-agents --host 127.0.0.1 --port 3100
pixel-agents --help

The default bind address is 127.0.0.1. Binding to 0.0.0.0 exposes the UI and WebSocket to the local network; do this only on a trusted network.

Open the URL the CLI prints - it carries a ?token= for this session. Any browser can watch the office without it, but installing or removing hooks (which edits your agent tool's own settings file, like the ~/.claude/settings.json) is only offered to a session that has the token, so an untokened client on the network cannot approve it. Open the bare address instead and the hooks toggle in Settings is refused, and reports the actual install state rather than appearing to work.

Treat that URL as a secret: the token is a bearer capability, not proof of being local. Whoever holds it can approve the hook install from anywhere the server is reachable — so don't paste the URL into a shared channel, and note that it also lands in your browser history and (unredacted) in the server's own request log.

Pass --no-terminal to disable the embedded terminal — watch agents without launching or attaching to them from the browser.

Running the extension and standalone together

The extension and standalone CLI can run at the same time. Each server registers under ~/.pixel-agents/servers/; the hook script sends events to all active registrations. VS Code and standalone keep separate agents, seats, and settings while using the shared office layout.

Stop a standalone server with Ctrl+C. It removes only its own registration.

Customizing the Office

Click Layout to edit the office:

Layouts can grow to 64×64 tiles by clicking the ghost border outside the current grid.

Office assets

Bundled furniture, floors, walls, carpets, characters, and pets live under webview-ui/public/assets/. Furniture manifests describe sprites, rotation groups, state groups, and animation frames.

Use Settings → Add Asset Directory to load external characters, pets, and furniture. See docs/external-assets.md for furniture directory structure and manifest details. The visual asset manager at scripts/asset-manager.html helps create furniture manifests.

How It Works

Pixel Agents uses two Claude Code detection paths:

The Claude provider normalizes both sources into a shared AgentEvent model. AgentRuntime updates the central state store, and the active transport sends typed messages to the React webview. The office renders through Canvas 2D with pathfinding and character state machines.

Pixel Agents does not modify Claude Code. Its hook configuration and persistent data live under ~/.claude/ and ~/.pixel-agents/ respectively.

Architecture

The extension and CLI are bundled with esbuild; the webview is built with Vite. Unit tests use Vitest and Node's test runner, and end-to-end coverage uses Playwright against VS Code and standalone.

Development

git clone https://github.com/pixel-agents-hq/pixel-agents.git
cd pixel-agents
npm install
npm run build

Press F5 in VS Code to launch the Extension Development Host. To run the standalone bundle built from source:

node dist/cli.js

Common checks:

npm run check-types
npm run lint
npm test
npm run e2e

See CONTRIBUTING.md for the development workflow and e2e/README.md for the end-to-end suite.

Hosted Test Reports

Build the combined Allure report locally and stage it for Vercel:

npm run test
npm run e2e
npm run e2e -- --attach-videos-on-success
npm run vercel:prepare

Use npm run test:report to build the combined report without preparing the Vercel output, then npm run test:report:open to serve it locally.

The staged output serves the combined e2e, server, and webview Allure report at /reports/allure/; it does not include a standalone webview preview. GitHub Actions creates a Vercel Preview deployment only for same-repository pull requests targeting main. The deploy job expects VERCEL_TOKEN, VERCEL_ORG_ID, and VERCEL_PROJECT_ID secrets and skips fork pull requests.

Troubleshooting

Community & Contributing

Join the Discord to chat with other users and follow development. Use Issues to report bugs or request features, and Discussions for questions and ideas.

See CONTRIBUTING.md before opening a pull request and read our Code of Conduct before participating.

Supporting the Project

GitHub Sponsors Ko-fi

Star History

Star History Chart

License

Pixel Agents is available under the MIT License.

pixel-agents (pixel-agents-hq/pixel-agents)

Searching Database…

9.7K ·GitHub
Pixel-agents
Что это такое?Pixel Agents превращает ИИ-агентов для программирования, работающих в ваших терминалах, в анимированных персонажей в пиксельной графике, которые трудятся в маленьком офисе: ходят к столам, печатают, когда редактируют файлы, читают, когда что-то ищут, и наглядно сигнализируют вам, когда застряли и ждут ввода.
Это расширение VS Code или самостоятельное приложение?И то, и другое, из одной кодовой базы: расширение VS Code, которое рисует персонажей в панели, и отдельный CLI (npx pixel-agents), который запускает локальный сервер и показывает тот же офис в браузере. Это удобно для tmux, удалённой работы или сценариев без VS Code.
Как всё запустить?Для VS Code установите расширение из Marketplace или Open VSX, откройте панель Pixel Agents и нажмите '+ Agent', чтобы запустить Claude Code. Для CLI выполните 'npx pixel-agents' в папке проекта, которую хотите отслеживать: он выведет локальный URL с токеном сессии.
Какие ИИ-агенты поддерживаются и что нужно установить?Нужно установить и настроить CLI Claude Code. Пока это единственная эталонная реализация, а Codex, Gemini и Cursor запланированы на будущее. Для расширения VS Code нужна версия VS Code 1.105.0+, а для отдельного CLI — Node.js 20+.
Есть ли подводные камни с безопасностью в URL отдельного CLI?Выведенный URL содержит токен сессии, который работает как ключ доступа: любой, у кого он есть, может удалённо подтверждать установку хуков. Кроме того, он без маскировки попадает в историю браузера и в логи сервера, поэтому не передавайте его другим и не привязывайте сервер к 0.0.0.0 в недоверенных сетях.
Изменяет ли он Claude Code или трогает мои файлы?Нет. Pixel Agents не меняет сам Claude Code: его конфигурация хуков хранится в ~/.claude/, а постоянные данные — в ~/.pixel-agents/.
Как он понимает, что делает агент?Используются два способа. Режим хуков, где скрипт получает события Claude, такие как SessionStart, PreToolUse и Stop. И запасной эвристический режим, который сканирует JSONL-файлы сессий Claude в ~/.claude/projects/, если хуки недоступны.
Можно ли изменить планировку офиса?Да. Встроенный редактор позволяет рисовать полы и стены, расставлять и поворачивать мебель, добавлять питомцев, создавать именованные зоны, привязанные к папкам проекта, и импортировать или экспортировать планировку в JSON. Планировка может достигать 64x64 клеток.
Что происходит, когда работают несколько агентов или субагентов?Каждый терминал с агентом получает своего анимированного персонажа. Временные субагенты и постоянные напарники Claude (Agent Teams) появляются отдельными персонажами с разными ролями и своими изменениями жизненного цикла.
Можно ли запустить расширение VS Code и CLI одновременно?Да, они могут работать одновременно. Каждый регистрируется в ~/.pixel-agents/servers/ и ведёт своих агентов, места и настройки, при этом оба используют одну и ту же планировку офиса.
What are similar projects?ordewell, agentbox, wicked-studio, openrig, qwen-code, dsh-TUI, context-mode, plannotator
Which topics is it in?tmux, hooks, vscode-extension, vscode, websocket, dashboard, agents, agent, react, claude-code, npm, terminal
Creator
pixel-agents-hq
Size
3.6 MB
Stars
9.7K
Updated
CommitOct 16Releasev1.5.0Oct 17
Age
8mo
Commits · 90 Days