Guide · Open source

How to use Pixel Agents: VS Code and standalone CLI setup

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

Pixel Agents is an open-source tool that shows the AI coding agents running in your terminals as animated pixel-art characters that walk to desks and visibly show what they are doing. It ships as a VS Code extension and as a standalone CLI that serves the same office in a browser. This guide walks through requirements, both setup paths, the main settings and the safety points you need before using it.

Pixel Agentspixel-agents-hq/pixel-agents · ★ 10k · MIT Install options & downloads

Quick start

1Check requirements. Confirm Claude Code CLI is installed and configured, and that you are on Windows, Linux or macOS.
2Pick a path. Use the VS Code extension if you work in VS Code, or the standalone CLI if you use tmux, remote or other non-VS Code setups.
3Install. Install the extension from the VS Code Marketplace or Open VSX, or run npx pixel-agents from your project directory.
4Open the office. Open the Pixel Agents panel in VS Code, or open the URL the CLI prints in your browser.
5Launch an agent. Click + Agent, choose a Directory and launch Claude Code in it.
6Secure the CLI. Keep the tokenised URL private and keep the default 127.0.0.1 bind unless you are on a trusted network.

What you need before you install Pixel Agents

Pixel Agents is built around Claude Code, which is the reference agent today. You need the Claude Code CLI installed and configured before anything else will work. Other agents are not yet supported; they are on the roadmap.

Claude Code CLI installed and configured
VS Code 1.105.0 or later, if you use the VS Code extension
Node.js 20 or later, if you use the standalone CLI
Windows, Linux, or macOS

Install the VS Code extension and launch an agent

Install Pixel Agents from the VS Code Marketplace or Open VSX. Then open the Pixel Agents panel beside your terminal. To start an agent, click + Agent to open its drawer of Directories, and click one to launch Claude Code in it.

Your workspace folders appear in that drawer once you turn on Settings → Show Workspace Folders. To add your own directory, use + Directory and give it a name and a path, and optionally choose the Areas its agents should sit in. The pencil on a row you added lets you edit or delete it.

Install from the VS Code Marketplace or Open VSX
Open the Pixel Agents panel beside the terminal
Click + Agent, then click a Directory
Use Settings → Show Workspace Folders to list workspace folders
Use Settings → Watch All Sessions to include Claude sessions from other workspaces

Run the standalone CLI in a browser

The standalone CLI is useful for tmux, remote, and non-VS Code workflows. Run it from the workspace whose Claude sessions you want to see. It chooses a free local port and prints a URL to open in your browser.

To install the command globally instead of using npx, install it with npm and then run it by name.

Click + Agent and then a Directory to launch Claude Code; the agent's terminal opens in the browser
Use + Directory to add your own directories
Settings → Show Start Directory lists the directory the CLI was started from
Claude Code started in your own terminal is also picked up
On a phone, tap the + card to open the same drawer

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

npm install --global pixel-agents
pixel-agents

Choose a port or address for the CLI

By default the CLI picks a free port on each start. Use a fixed port when you want a bookmark or home-screen link to keep working. The default bind address is 127.0.0.1, which is local only.

Binding to 0.0.0.0 exposes the UI and WebSocket to the local network. Only do this on a trusted network.

--port sets a fixed port
--host sets the bind address
--no-terminal is available as a flag
--help lists the options

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

Understand the access token and security limits

The URL the CLI prints includes a ?token= for that server. Anyone can watch the office without it. Installing or removing hooks, launching agents from the browser, and attaching to their terminals require the token. Opening the bare address without it means the hooks toggle is refused and the + Agent button explains what it needs.

Standalone keeps the same token across restarts, stored in ~/.pixel-agents/standalone-token, readable only by you. Because the port changes on each start unless you set --port, a bookmark works only when you also keep the port fixed.

Treat the URL as a secret. The token is a bearer capability, not proof that you are local. Pixel Agents is not a hardened multi-user service.

Watchers can view the office without the token
Hook changes, launching agents and terminal attachment need the token
Keep the URL private

Optional features: skip permissions, sounds and layouts

Settings → Skip Permissions runs Claude with --dangerously-skip-permissions. It stays on for every agent launched from that host until you turn it off. The README says to use it only when you accept the security implications.

Other features include speech bubbles for agents waiting for input or permission, optional sound chimes, an office layout editor, saved layouts shared across VS Code windows, and Areas that map workspace folders to parts of the office.

Speech bubbles show when an agent is waiting for input or awaiting permission
Sound notifications are optional
Office layout editor for floors, walls and furniture
Sub-agents and Agent Teams appear as separate characters

What people use it for

Watching several Claude Code sessions running at once in one visual overview
Seeing agent activity beside your VS Code terminals
Monitoring agents in tmux or on a remote machine through a browser
Organising agents by project with directories mapped to office Areas

Frequently asked questions

Is Pixel Agents free?

Pixel Agents is open source under the MIT licence. The source does not mention pricing for it, and the Claude Code CLI is a separate requirement you must have installed and configured.

What do I need to install Pixel Agents?

You need the Claude Code CLI installed and configured, plus VS Code 1.105.0 or later for the extension or Node.js 20 or later for the standalone CLI. It runs on Windows, Linux or macOS.

How do I run Pixel Agents in a browser?

Change to your project directory and run npx pixel-agents. The CLI prints a URL with a token, which you open in your browser. You can also install it globally with npm install --global pixel-agents.

Does Pixel Agents work with agents other than Claude Code?

Not yet. Claude Code is the reference implementation today, and other tools such as Codex, Gemini and Cursor are on the roadmap.

Is it safe to expose Pixel Agents on my network?

Binding to 0.0.0.0 exposes the UI and WebSocket to the local network, so only do it on a trusted network. The access token is a bearer secret, so anyone holding the URL can perform the token-protected actions.

Why does my bookmarked Pixel Agents link stop working?

The standalone CLI keeps the same token across restarts, but the default port is picked fresh on each start. Use --port with a fixed number so the bookmarked URL still points to the same server.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Pixel Agents suits developers who run several Claude Code sessions and want a playful visual overview, either inside VS Code or in a browser via the standalone CLI. If you do not use Claude Code, or you need a hardened multi-user service with access controls, choose a different tool.

Install options & downloads