npm package: @patrax/office-viz
Description: Pixel art office visualization plugin for OpenClaw - see your agents as animated characters
Author: OpenClaw Community
Latest version: 1.1.0

# 🏢 OpenClaw Office Visualization Plugin

A pixel art office visualization plugin for OpenClaw that displays your running agents as animated characters in a virtual office environment.

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![OpenClaw](https://img.shields.io/badge/openclaw-plugin-purple.svg)

## ✨ Features

- **Real-time Agent Visualization**: See your OpenClaw agents as animated pixel art characters
- **Status Indicators**: Visual representation of agent states (active, idle, waiting, offline)
- **Interactive UI**: Hover over characters to see agent details, click for more info
- **Office Environment**: Desks, furniture, plants, and more create an immersive office scene
- **Automatic Updates**: Agents appear/disappear as sessions start and end
- **Responsive Design**: Scales to fit any screen size
- **Dark Theme**: Easy on the eyes, matches the OpenClaw dashboard aesthetic

## 📸 Preview

```
┌─────────────────────────────────────────────────────────────┐
│ 🏢 OpenClaw Office           ● 3 active  ● 2 idle  ○ 1 off │
├─────────────────────────────────────────────────────────────┤
│  🌿                                                    🌿   │
│      ┌───┐     ┌───┐     ┌───┐                             │
│      │ 💻│     │ 💻│     │ 💻│                        ☕   │
│      └───┘     └───┘     └───┘                             │
│       👤        👤        👤                           💧   │
│     active    active     idle                              │
│                                                            │
│      ┌───┐     ┌───┐     ┌───┐                             │
│      │ 💻│     │ 💻│     │   │                             │
│      └───┘     └───┘     └───┘                             │
│       👤        👤                                         │
│      idle    waiting                        🛋️             │
└─────────────────────────────────────────────────────────────┘
```

## 🚀 Installation

### From npm (recommended)

```bash
npm install @openclaw-community/office-viz
# or
pnpm add @openclaw-community/office-viz
```

### From source

```bash
git clone https://github.com/openclaw-community/office-viz.git
cd office-viz
pnpm install
pnpm build
```

### Enable in OpenClaw

Add to your `openclaw.yaml`:

```yaml
plugins:
  office-viz:
    enabled: true
    basePath: /office
    theme: default
    showInactiveAgents: true
    animationSpeed: 1.0
```

Restart the OpenClaw Gateway, then visit `http://your-gateway:4242/office`

## ⚙️ Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable the plugin |
| `basePath` | string | `/office` | URL path for the visualization |
| `theme` | string | `default` | Color theme (`default`, `dark`, `light`) |
| `showInactiveAgents` | boolean | `true` | Show offline agents in the office |
| `animationSpeed` | number | `1.0` | Animation speed multiplier (0.5 - 2.0) |

## 🛠️ Development

### Prerequisites

- Node.js 18+
- pnpm 8+

### Setup

```bash
# Clone the repository
git clone https://github.com/openclaw-community/office-viz.git
cd office-viz

# Install dependencies
pnpm install

# Build everything
pnpm build

# Or develop with hot reload
pnpm dev:ui
```

### Project Structure

```
office-viz/
├── src/                      # Plugin backend
│   └── index.ts             # Main plugin entry point
├── ui/                       # Frontend application
│   ├── src/
│   │   ├── main.ts          # UI entry point
│   │   ├── styles.css       # Global styles
│   │   └── office/          # Core visualization
│   │       ├── OfficeApp.ts # Main application class
│   │       ├── Renderer.ts  # Canvas rendering
│   │       ├── SpriteManager.ts # Character sprites
│   │       ├── ApiClient.ts # API communication
│   │       └── types.ts     # TypeScript definitions
│   ├── index.html
│   └── vite.config.ts
├── openclaw.plugin.json     # Plugin manifest
├── package.json
└── README.md
```

### API Endpoints

The plugin exposes these endpoints:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/office` | GET | Main visualization UI |
| `/office/api/agents` | GET | List all agent states |
| `/office/api/presence` | GET | Get presence information |
| `/office/api/sessions` | GET | Get active sessions |
| `/office/api/config` | GET | Get plugin configuration |

### Testing Locally

1. Build the plugin:
   ```bash
   pnpm build
   ```

2. Link to your OpenClaw installation:
   ```bash
   cd /path/to/openclaw
   pnpm link /path/to/office-viz
   ```

3. Add to `openclaw.yaml` and restart

4. For UI development with hot reload:
   ```bash
   pnpm dev:ui
   ```
   Then visit `http://localhost:5173/office/`

## 🎨 Customization

### Adding Custom Sprites

You can replace the procedural character sprites with custom pixel art:

1. Create sprite sheets (32x48px per frame)
2. Place in `ui/public/sprites/`
3. Update `SpriteManager.ts` to load from files

### Modifying Office Layout

Edit the `DEFAULT_LAYOUT` in `OfficeApp.ts`:

```typescript
const DEFAULT_LAYOUT: OfficeLayout = {
  width: 12,  // Grid width
  height: 10, // Grid height
  desks: [
    { id: 1, x: 2, y: 2, occupied: false },
    // Add more desks...
  ],
  furniture: [
    { type: 'plant', x: 0.5, y: 1, width: 1, height: 1 },
    // Add more furniture...
  ]
}
```

## 🤝 Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Ideas for Contributions

- 🎨 New character designs/animations
- 🪑 Additional furniture types
- 🎵 Sound effects
- 📱 Mobile-optimized layout
- 🌙 Additional themes
- 🗺️ Layout editor
- 📊 Agent activity graphs

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

- Inspired by [pixel-agents](https://github.com/pablodelucca/pixel-agents) for VS Code
- Built for the [OpenClaw](https://openclaw.ai) community
- Pixel art rendering techniques from various game dev resources

## 📚 Related

- [OpenClaw Documentation](https://docs.openclaw.ai)
- [OpenClaw Plugins Guide](https://docs.openclaw.ai/tools/plugin)
- [Community Plugins](https://docs.openclaw.ai/plugins/community)

---

Made with ❤️ for the OpenClaw community