npm package: @moxxy/virtual-office-plugin
Description: <p align="center">   <img src="https://moxxy.ai/logo-gradient.svg" alt="moxxy" width="120" /> </p>
Latest version: 0.0.7

<p align="center">
  <img src="https://moxxy.ai/logo-gradient.svg" alt="moxxy" width="120" />
</p>

<h3 align="center">@moxxy/virtual-office-plugin</h3>

<p align="center">
  Pixel-art virtual office visualization for <a href="https://github.com/moxxy-ai/moxxy">Moxxy</a> agents. Watch your AI agents work, collaborate, and execute tasks in real time.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@moxxy/virtual-office-plugin"><img src="https://img.shields.io/npm/v/@moxxy/virtual-office-plugin?style=flat-square&color=cb3837&logo=npm&logoColor=white&label=npm" alt="npm"></a>
  <img src="https://img.shields.io/badge/node-%E2%89%A522-5FA04E?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22+">
  <a href="#license"><img src="https://img.shields.io/badge/license-MIT%20%2F%20Apache--2.0-blue?style=flat-square" alt="License"></a>
</p>

<p align="center">
  <a href="https://docs.moxxy.ai">Documentation</a> ·
  <a href="https://moxxy.ai">Website</a> ·
  <a href="https://github.com/moxxy-ai/moxxy">GitHub</a>
</p>

---

Runs as a Moxxy plugin, connecting to the gateway's REST API and SSE event stream. Renders a 2D pixel-art office where each agent appears as an animated character - walking to desks, typing while running tasks, and idling when waiting for work.

## Features

- **Virtual office** - pixel-art 2D environment with desk pods, conference table, and aisles rendered via Phaser 3
- **Live agent visualization** - agents animate in real time: walking, sitting, typing at desks based on their execution state
- **Agent management** - create, delete, and monitor agents from the sidebar
- **Task execution** - launch runs, stream results, and watch agents work with real-time SSE updates
- **Chat & mission log** - view agent conversation history, tool calls, and execution steps
- **Command launcher** - send commands to agents directly from the UI
- **Agent graveyard** - historical snapshots of completed/terminated agents with full chat and log history
- **Connection monitoring** - live connection status with automatic reconnection and exponential backoff
- **Color-coded agents** - 6 distinct color palettes for visual differentiation

## Install

```bash
moxxy plugin install @moxxy/virtual-office-plugin
```

## Usage

```bash
# Start the virtual office
moxxy plugin start @moxxy/virtual-office-plugin

# Or use the interactive plugin menu
moxxy plugin
```

The virtual office opens at `http://localhost:17901`. Navigate to **Settings** to configure your gateway URL and API token if they aren't injected automatically.

## Development

Requires Node.js 22+ and npm.

```bash
git clone <repo>
cd virtual-office-plugin
npm install
npm run dev
```

The dev server starts on port 17901 with a proxy that forwards `/v1/*` requests to the gateway at `localhost:3000`.

### Build

```bash
npm run build
```

Produces a production bundle in `dist/`.

### Preview production build

```bash
npm run plugin:start
```

Serves the built `dist/` directory using a zero-dependency static server.

### Testing

```bash
npm run test              # Unit tests
npm run test:watch        # Watch mode
npm run test:integration  # Integration tests
npm run test:e2e          # Playwright end-to-end tests
```

## How it works

The plugin is a single-page application built with React 19, Phaser 3, and Zustand. At runtime it ships pre-built static assets and a lightweight Node.js file server (`serve.js`) - no build tools or framework dependencies are required.

When started by the Moxxy CLI, the plugin receives environment variables (`MOXXY_API_URL`, `MOXXY_TOKEN`, `PORT`) and serves the virtual office on the allocated port. The app subscribes to the gateway's SSE event stream and maps agent state changes to character animations in the Phaser scene.

### Architecture

```
┌─────────────────────────────────────────────────────┐
│                    App.tsx                           │
│  ┌──────────┐  ┌────────────────┐  ┌─────────────┐ │
│  │  Agent   │  │    Phaser      │  │   Agent     │ │
│  │ Sidebar  │  │ OfficeScene    │  │  Detail     │ │
│  │ (left)   │  │  (center)      │  │  Panel      │ │
│  └──────────┘  └────────────────┘  │  (right)    │ │
│                                    └─────────────┘ │
└────────────────────┬────────────────────────────────┘
                     │
              ┌──────┴──────┐
              │ WorldStore  │  Zustand - agents, chat, missions
              └──────┬──────┘
                     │
              ┌──────┴──────┐
              │EventAdapter │  Maps SSE events → state updates
              └──────┬──────┘
                     │ SSE / REST
              ┌──────┴──────┐
              │  Gateway    │  Moxxy gateway API
              │  Client     │
              └─────────────┘
```

## Environment variables

Set automatically when launched via `moxxy plugin start`:

| Variable | Description |
|---|---|
| `MOXXY_API_URL` | Gateway base URL (e.g. `http://localhost:3000`) |
| `MOXXY_TOKEN` | API bearer token |
| `PORT` | Port to serve the virtual office on |
| `MOXXY_PLUGIN_NAME` | Plugin package name (`@moxxy/virtual-office-plugin`) |
| `MOXXY_PLUGIN_PORT` | Allocated port (same as `PORT`) |
| `MOXXY_HOME` | Moxxy data directory (default `~/.moxxy`) |
| `VITE_MOXXY_API_URL` | Gateway URL exposed to browser code during development |
| `VITE_MOXXY_TOKEN` | API token exposed to browser code during development |

## Links

- [Documentation](https://docs.moxxy.ai)
- [Website](https://moxxy.ai)
- [GitHub](https://github.com/moxxy-ai/moxxy)

## License

Dual-licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE) at your option.