pixel-agents is a free, open source frameworks & platforms project written in TypeScript and released under MIT. It has 10,282 GitHub stars, 1,753 forks and 105 open issues, and was last pushed 9 days ago. On this registry it ranks #44 of 146 tracked projects in Frameworks & Platforms, with 5 head-to-head comparisons available.

What is pixel-agents?

Pixel Agents is an MIT-licensed TypeScript tool that turns the AI coding agents running in your terminals into animated pixel-art characters working in a tiny office, and it is aimed at developers using Claude Code who want to launch, watch and manage those agents from a single visual surface.

What it is

Pixel Agents is a visual layer over the coding agents already running in terminals. Each agent terminal is assigned its own pixel-art character, and those characters walk to their desks, sit down, type when the agent is editing files, read when it is searching, and flag the user visually when an agent is stuck waiting for input. The office is not just a display: it is also the place from which agents are launched into a project, given a character, and monitored for how much context they have left. It ships in two forms from the same codebase, a standalone CLI and a VS Code extension.

The concrete problem it addresses is the flatness of terminal-based agent work. Agents running in terminals produce streams of text, and once several are running in parallel it becomes difficult to tell at a glance which one is writing files, which one is blocked waiting for permission, and which one is close to exhausting its context. Pixel Agents replaces the undifferentiated terminal tab as the interface for monitoring and launching agents, while the terminals themselves remain underneath — in VS Code terminals for the extension, and in an embedded terminal for the browser-based standalone version. It lives in the Claude Code ecosystem and installs through the VS Code Marketplace, Open VSX, and npm.

Key capabilities

  • One agent, one character: every agent terminal gets its own animated character, and sub-agents and teammates show up as their own characters too.
  • Live activity tracking: characters animate based on what the agent is actually doing, including writing, reading and running commands.
  • Notifications: speech bubbles, plus optional chimes, appear when an agent needs input or permission or finishes its turn.
  • Office layout editor: design the office with floors, walls, furniture and named Areas; layouts are saved across windows, export as JSON, and accept external asset packs.
  • Character design: a wardrobe of bodies, hair, clothes and accessories, colour pickers, a pixel editor and custom items, with pixel art based on JIK-A-4's Metro City pack.
  • Usage and context bars: health bars for plan limits, and a bar on every agent showing the context it has left.
  • Recent conversations: past sessions are listed per Directory and can be resumed with one click as the character they had.

Who uses it and how

  • VS Code users install the extension from the VS Code Marketplace or Open VSX; agents launch into VS Code terminals and the characters render in the panel area, on VS Code 1.105.0 or later.
  • Terminal, remote and tmux workflows use the standalone CLI, where npx pixel-agents starts a local server and serves the same office as a browser app with an embedded terminal.
  • Mobile and remote access works through Tailscale, where the standalone office can become an app with the office and the terminal a swipe apart.
  • People running several agents at once rely on sub-agents and teammates appearing as separate characters, so parallel work stays visible in the office.
  • The extension and the CLI can run side by side: both share the office layout but keep separate agents and settings.

Getting started

Install the extension from the VS Code Marketplace or Open VSX, or run npx pixel-agents for the standalone browser version, after installing and configuring the Claude Code CLI; the CLI requires Node.js 20 or later. Both run on Windows, Linux and macOS.

How it compares

No comparable tools are named in the facts for this entry, so Pixel Agents stands alone in this registry at present. It is best understood as a visual management layer for Claude Code sessions rather than a replacement for the agent CLI itself.

When to use it — and when not

It suits developers running Claude Code who want parallel sessions to be legible at a glance, particularly across VS Code, tmux or remote machines. It is not the right choice for anyone working with Codex, Gemini, Cursor or other CLIs today: Claude Code is the only supported agent, and the others are only on the roadmap. Prospective users should also note the prerequisites, which include a configured Claude Code CLI, Node.js 20 or later for the standalone CLI, and VS Code 1.105.0 or later for the extension.

project readme (upstream, from github) — read inline

version marketplaces npm downloads stars license discord

🌐 Website • 🛒 VS Code • 🛒 Open VSX • 📦 npm • 👾 Discord • 🤝 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. The office is also where you run them: launch an agent into a project, pick its character, and see how much context it has left.

It ships in two forms from the same codebase:

  • Standalone CLI — npx pixel-agents starts a local server and serves the same office as a browser app, useful for tmux, remote, and non-VS Code workflows.
  • VS Code extension — VS Code Marketplace and Open VSX. Agents launch into VS Code terminals; characters render in the panel area.

Claude Code is supported today; Codex, Gemini, Cursor, and others are on the roadmap. Want to add support for your favourite CLI? Join our Discord and let us know!

Pixel Agents screenshot

Features

  • One agent, one character — every agent terminal gets its own animated character
  • Live activity tracking — characters animate based on what the agent is actually doing (writing, reading, running commands). Sub-agents and teammates show up as their own characters
  • Notifications — speech bubbles, plus optional chimes, when an agent needs input or permission or finishes its turn
  • Office layout editor — design your office with floors, walls, furniture, and named Areas; layouts are saved across windows, export as JSON, and take external asset packs
  • Your own team — design your agents: a wardrobe of bodies, hair, clothes and accessories, colour pickers, a pixel editor, and custom items. The pixel art is based on the amazing work of JIK-A-4, Metro City.
  • In the browser and on your phone — the standalone office launches agents into an embedded terminal. On a phone, via Tailscale, it can become an app with the office and the terminal a swipe apart
  • Recent conversations — past sessions listed per Directory, resumed with one click as the character they had
  • Usage and context bars — health bars for your plan limits, and one on every agent for the context it has left
  • Office radio — procedural 8-bit background music with moods and shareable song codes

Requirements

  • Claude Code CLI installed and configured
  • VS Code extension: VS Code 1.105.0 or later
  • Standalone CLI: Node.js 20 or later
  • Windows, Linux, or macOS

Getting Started

The VS Code extension and the standalone CLI can run side by side: both share the office layout but keep separate agents and settings.

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 + (bottom left) to open its drawer of Directories, then click one to launch Claude Code in it. The drawer is empty at first: turn on Settings → Show Workspace Folders, or add a folder with + Directory (see Directories below).

To use Claude with --dangerously-skip-permissions, turn on Settings → Skip Permissions. It stays on for every agent launched from that host until you turn it off. 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 anywhere:

npx pixel-agents

The CLI prints a local URL. Click + to open the drawer of Directories: add one with + Directory, or turn on Settings → Show Start Directory to list the folder you started in. Pick a Directory to launch Claude Code in the browser's embedded terminal (on a phone, tap the + card). Sessions started in your own terminal show up too. To install globally:

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 --no-terminal
pixel-agents --help

The printed URL carries a ?token=. Without it you can watch the office in a sort of read-only mode: no agents can be launched, terminals are not shown, and layout and settings cannot be edited. The token is kept in ~/.pixel-agents/standalone-token, so a bookmark keeps working if you also fix --port. Treat the URL as a secret: whoever holds it can do all of the above.

On your phone, via Tailscale

  1. Install Tailscale on the computer running Pixel Agents and on your phone, both signed in to the same tailnet.

  2. Start the server on a fixed port, allowing the computer's tailnet name:

    pixel-agents --port 3100 --allowed-host my-computer.my-tailnet.ts.net
    
  3. Serve it to your tailnet over HTTPS:

    tailscale serve --bg 3100
    
  4. On your phone, open https://my-computer.my-tailnet.ts.net/?token=… (the ?token= from the URL the CLI printed) and add it to the home screen. The fixed port keeps that shortcut working across restarts.

Only devices on your tailnet can reach it.

Customizing the Office

Layout

Click Layout to edit the office: paint floors, walls and carpets, place and recolour furniture, add pets you can click on, and paint named Areas that a Directory's agents prefer to sit in. Layouts can be exported and imported as JSON.

Office assets

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.

Directories

A Directory is a folder you launch agents into. Click + to open the drawer, then + Directory to add one: a name, a path (suggested from your past Claude Code sessions), and optionally the Areas its agents should sit in and the characters they wear by default. The pencil on a row you added edits or deletes it; on a phone, long-press the row.

Your workspace folders (VS Code) or the directory the CLI started in (standalone) are listed too once you turn on Settings → Show Workspace Folders or Show Start Directory.

Characters

Open the roster from the arrow beside + and press a character's pencil (or + New) to open the Characters view. Dress a character from the wardrobe tabs, recolour any piece, and touch up pixels in the editor; a piece you redraw can be saved as a custom item for the rest of the cast. Nothing changes in the office until you press Save. Characters export as a PNG or a config file, and the whole roster as a zip.

Picking a character in the roster and then a Directory launches an agent as that character. In a Directory's settings you can also list its default characters, so its agents are recognisable at a glance.

Where This Is Going

The vision is to play a game and 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.

Three things get there, and they are happening in parallel, not in sequence:

  • Actually a game. Scores for whatever you care about. Furniture that does things. Offices you open like save files, one per project.
  • Expand the orchestration frontier. Embedded orchestration. 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.
  • 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.

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

How It Works

Pixel Agents uses two Claude Code detection paths:

  • Hooks mode (default) — a hook script receives Claude events such as SessionStart, PreToolUse, PermissionRequest, and Stop. It discovers active Pixel Agents servers and sends authenticated events to each one.
  • Heuristic mode (fallback) — when hooks are unavailable, the runtime infers agent status by scanning Claude's JSONL session transcripts under ~/.claude/projects/. Transcripts are also read in hooks mode for details not present in an event.

Pixel Agents does not modify Claude Code. Its hook configuration and persistent data live under ~/.claude/ and ~/.pixel-agents/ respectively. The usage bars are opt-in (Settings → Usage Bars): Claude Code reports plan limits only to its status line, so turning them on wraps your statusLine command in ~/.claude/settings.json (yours keeps running unchanged), and turning them off restores it.

Development

To build from source, run the tests, or add support for another agent CLI, see CONTRIBUTING.md. It covers setup, the project structure, how an event reaches the office, the asset format, and the hosted test reports. The end-to-end suite is described in e2e/README.md.

Troubleshooting

  • Standalone will not start: verify Node.js 20+, omit --port to choose a free port, or select another fixed port.
  • An agent is missing: confirm Settings → Instant Detection (Hooks) is on and that the session belongs to the current workspace. Enable Watch All Sessions if needed.
  • The UI looks disconnected: open Settings → Debug View to inspect the server connection, transcript path, and latest agent data.
  • Extension and standalone are both running: this is supported. Current versions create separate files under ~/.pixel-agents/servers/; stopping one does not remove the other.

Still stuck? Ask in Discord or open an issue.

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.

Frequently asked questions

Is pixel-agents free to use?

pixel-agents is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does pixel-agents do?

A playful way to manage your AI workforce

What is pixel-agents written in?

pixel-agents is primarily written in TypeScript. Its source is publicly available at https://github.com/pixel-agents-hq/pixel-agents, and it has 10,282 GitHub stars.