English | 简体中文
Watch Codex subagents work in a live pixel-art office. Each subagent becomes an employee with a desk, a moving speech bubble, a task drawer, delivery and rest animations, and a visible failure state.
Pixel Office is a community project for the Codex desktop app. It is not an official OpenAI product.
| Codex event | Office behavior |
|---|---|
spawn_agent starts a subagent |
A new employee enters and walks to an available desk |
| The subagent produces output | A cloud bubble follows the employee and shows the latest message |
| You click an employee | A side drawer shows the employee name, current state, main task, and complete output history |
| The subagent completes its task | The employee carries documents to the Boss, delivers them, and moves to a rest area |
| An existing subagent receives more work | The employee is recalled to its desk |
| The task fails, pauses, or is interrupted | The employee discards the documents, returns to the desk, and enters a red failed state |
| More than eight subagents are active | Additional employees wait near the entrance with briefcases |
The Boss displays a short speech bubble every 20-40 seconds while at least one employee is working.
- macOS. The one-command installer uses
launchd, and automatic Codex sidebar registration currently targets the macOS desktop app. - Codex desktop app and Codex CLI with plugin support.
- Node.js 18 or newer.
- Python 3, used by
install.shto update the local Codex configuration. - Port
8791available for the live bridge. Demo mode can use another port.
Pillow is only required when regenerating the pixel-art assets. It is not needed to install or run the plugin.
Clone or download this repository, then run:
cd pixel-office
./install.shThe installer performs the following local changes:
- Creates a
local-devmarketplace in a siblinglocal-marketplacedirectory and points it at this source tree. - Registers that marketplace and enables
pixel-office@local-devin~/.codex/config.toml. - Runs
codex plugin add pixel-office@local-devto materialize the plugin in the Codex cache. - Installs the
ai.pixeloffice.bridgeLaunchAgent so the bridge starts at login and restarts after a crash.
Review install.sh before running it if you do not want those
configuration changes. To install without the persistent LaunchAgent, use:
./install.sh --no-daemonAfter installation, start a new Codex thread so the app loads the plugin's skill and MCP server.
No Pixel Office prompt is required. When a Codex conversation starts
subagents, the plugin asks Codex to ensure the bridge is running and open
http://localhost:8791/ in the app's right sidebar. The bridge also registers
Pixel Office in the sidebar's local-server list as a fallback.
Pixel Office observes subagents; it does not create them. Start a task that uses Codex collaboration/subagents. Employees will appear as those subagents start working.
If the sidebar does not open automatically, open the local-server entry named Pixel Office · 子智能体办公室 or visit:
Click an employee, not its speech bubble, to open the detail drawer. The drawer updates in real time and contains the employee's task plus every output message observed for that subagent.
The bridge has no npm dependencies or build step.
# Live mode: read Codex session logs and serve the office
node server/server.mjs --port 8791
# Demo mode: run a loop of scripted employees without a Codex task
node server/server.mjs --demo --port 8792
# Replay one root rollout together with its discovered subagent rollouts
node server/server.mjs --replay /path/to/rollout.jsonl --speed 20Open http://localhost:8792/ for the demo. To check whether the live bridge is already running:
curl http://localhost:8791/api/state~/.codex/sessions/**/rollout-*.jsonl
|
| incremental, read-only polling
v
server/server.mjs
| parses collaboration and subagent lifecycle events
| exposes snapshot JSON and Server-Sent Events
v
public/
| Canvas 2D scene, animation state machine, bubbles, and detail drawer
v
Codex right sidebar or a regular browser
- The bridge uses only Node.js standard-library modules.
- The frontend uses plain HTML, CSS, JavaScript, and Canvas 2D.
- Updates follow complete messages written to rollout logs; they are not token-by-token streaming.
- The bridge reads Codex rollout files but does not write to
~/.codex.
See docs/DEVELOPMENT.md for the event formats, state
machine, rendering architecture, installation internals, asset pipeline, and
regression checklist.
Pixel Office reads recent rollout-*.jsonl files under
~/.codex/sessions. Those files can contain task prompts and subagent output.
The bridge makes that content available through /api/state and /events
without authentication, so treat port 8791 as sensitive.
Current version 0.1.0 uses Node.js's default listen host, which can expose
the bridge on other network interfaces. Do not port-forward it, expose it to
the internet, or run it on an untrusted network without a firewall. A future
release should bind explicitly to 127.0.0.1 and optionally add access
controls.
The bridge does not make outbound network requests. The installer does write the local marketplace and Codex configuration described in the Installation section, and the running bridge updates the Codex sidebar's local-server registry on a best-effort basis.
Recent Codex builds may encrypt the message argument passed to
spawn_agent in rollout logs. When that happens, Pixel Office cannot display
the full original prompt and falls back to task_name as the main task.
pixel-office/
├── .codex-plugin/plugin.json Codex plugin manifest
├── .mcp.json MCP server registration
├── skills/pixel-office/ Implicit invocation and sidebar behavior
├── server/server.mjs Rollout parser, state bridge, SSE, static server
├── server/mcp.mjs MCP status tool and bridge bootstrap
├── public/ Canvas office, drawer UI, and generated PNG assets
├── tools/ Pillow-based pixel-art generators
├── docs/DEVELOPMENT.md Architecture and development notes
└── install.sh Local marketplace and macOS installer
Run the deterministic demo on a separate port while editing the frontend:
node server/server.mjs --demo --port 8792After changing plugin source, update the Codex cache and restart the bridge:
./install.sh
launchctl kickstart -k "gui/$(id -u)/ai.pixeloffice.bridge"Regenerate the checked-in pixel-art PNG files only when changing the art pipeline:
python3 -m pip install Pillow
cd tools
python3 draw_workers.py
python3 draw_furniture.py
python3 make_props.pyUse the demo and replay modes to verify employee click targets, output-history updates, bubble anchors, delivery order, rest positions, recall, and failure animations before opening a pull request.
- Automatic installation, persistence, and sidebar registration are currently macOS-specific.
- Live mode follows the newest root Codex session tree rather than showing multiple sessions at once.
- Speech bubbles update once per complete logged message, not per token.
- If a subagent process disappears without a failure, interruption, or completion event in the rollout, it can remain shown as working because there is no inactivity timeout yet.
- Automatic sidebar opening depends on Codex host capabilities. The registered local-server entry and direct URL remain available as fallbacks.
The office opens but no employees appear
Live mode only displays the newest Codex session tree, and that thread must actually start subagents. Use demo mode to verify the UI independently.
Port 8791 is already in use
curl http://localhost:8791/api/state
lsof -nP -iTCP:8791 -sTCP:LISTENIf the first command returns Pixel Office state, the existing bridge is the expected process and a second server is unnecessary.
The installed plugin does not reflect source changes
Run ./install.sh again, then start a new Codex thread. Codex materializes a
plugin cache; editing this repository does not automatically update an
already-loaded conversation.
The task drawer shows only a short task name
The full spawn_agent.message may be encrypted in the local rollout. Pixel
Office uses task_name as the safe fallback.
The LaunchAgent fails to start
Inspect /tmp/pixel-office.log, then verify that node is available in your
shell and that port 8791 is free.
Remove the materialized plugin and stop the persistent bridge:
codex plugin remove pixel-office@local-dev
launchctl bootout "gui/$(id -u)/ai.pixeloffice.bridge"
rm "$HOME/Library/LaunchAgents/ai.pixeloffice.bridge.plist"Then remove the [marketplaces.local-dev] and
[plugins."pixel-office@local-dev"] sections from ~/.codex/config.toml if
that marketplace is no longer used. The installer also created the sibling
local-marketplace directory; remove it only after confirming it contains no
other plugins you need.
Issues and focused pull requests are welcome. For behavior changes, include a short reproduction and verify both demo mode and a real or replayed subagent session. Keep generated assets and their source scripts in sync.
Licensed under the MIT License.