Pixel Agents

To use Pixel Agents within VS Code:

1. Install the extension from the VS Code Marketplace or Open VSX.
2. Open the Pixel Agents panel located beside the terminal.
3. Click + Agent to launch Claude Code. If you are in a multi-root workspace, ensure you select the desired folder first.

Tips:

• Skip permissions mode: To use Claude with --dangerously-skip-permissions, hover over the + Agent button and select the Skip permissions mode button.
• Watch external sessions: To include Claude sessions started outside the extension, enable Settings → Watch All Sessions.

You can load custom or third-party pixel art asset packs into Pixel Agents by adding an external directory. Once added, assets appear in the furniture palette immediately and are automatically reloaded on restart. The directory path is stored in ~/.pixel-agents/config.json.

1. Open the Pixel Agents panel and click Settings.
2. Click Add Asset Directory and select your folder.
3. To remove a directory, open Settings and click the X next to the path.

To execute the end-to-end test suite for Pixel Agents, use the following command:

npm run test:e2e

Note: The test inventory is auto-generated by scripts/generate-e2e-inventory.mjs. If you add or remove tests, you should re-run the generator to prevent CI failures due to drift.

The Standalone CLI is useful for tmux, remote, or non-VS Code workflows. It serves the office as a browser app.

Run via npx: Navigate to your project directory and run:

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

Global Installation:

npm install --global pixel-agents
pixel-agents

CLI Options: You can specify a fixed host or port:

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

Note: The CLI does not launch Claude for you; you must start Claude Code in a terminal within the same workspace manually. The default bind address is 127.0.0.1.

You can run both the VS Code extension and the standalone CLI at the same time.

• Each server registers under ~/.pixel-agents/servers/.
• The Claude hook script sends events to all active registrations.
• VS Code and the standalone CLI maintain separate agents, seats, and settings, but they share the same office layout.
• To stop a standalone server, use Ctrl+C (this only removes that specific registration).

External asset directories must follow a specific structure where each furniture item resides in its own subfolder containing a manifest.json and its corresponding PNG sprite files. The folder name is arbitrary; the id field within the manifest.json is used for identification.

my-assets/
  assets/
    furniture/
      MY_CHAIR/
        manifest.json
        MY_CHAIR.png
      MY_DESK/
        manifest.json
        MY_DESK_FRONT.png
        MY_DESK_SIDE.png

To contribute to or develop Pixel Agents, follow these steps:

1. Clone and install dependencies:

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

2. Launch Extension Development Host: Press F5 in VS Code.
3. Run standalone bundle from source:

node dist/cli.js

Common Development Commands:

• npm run check-types: Type checking
• npm run lint: Linting
• npm run test: Unit tests
• npm run e2e: End-to-end tests

The Pixel Agents e2e suite uses Playwright to test the VS Code extension and the standalone npx pixel-agents server. You can run the full suite, filter by specific functional areas using @area: tags, or run in headed mode to watch the Chromium browser.

cd pixel-agents
npm run compile && npm run e2e               # full suite (~10 min)

npm run e2e -- --grep "@area:spawn"          # filter by area tag
npm run e2e -- --grep "@area:cross-cutting"
npm run e2e -- --headed                      # watch chromium for standalone test

npm run e2e:inventory                        # regenerate the inventory section
npm run test:report                          # build the Allure dashboard
npm run test:report:open                     # serve + open the Allure dashboard

Before using Pixel Agents, ensure you meet the following requirements:

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

Use the Layout editor to design your workspace:

• Environment: Paint floor patterns, walls (with color/contrast controls), and auto-tiling carpets.
• Furniture: Place, rotate, recolor, select, and remove furniture items.
• Pets: Add animated pets and interact with them by clicking.
• Areas: Create named Areas, paint their tiles, and assign workspace folders to them to seat agents automatically.
• Grid: Layouts can expand up to 64×64 tiles by clicking the ghost border outside the grid.
• Persistence: Import or export complete layouts as JSON.

Adding External Assets: To load custom characters, pets, or furniture, go to Settings → Add Asset Directory. Bundled assets are located in webview-ui/public/assets/.