@syv-ai/pixel-agents-watcher

Standalone JSONL transcript watcher for Pixel Agents. Monitors Claude Code activity on your machine and streams agent events to one or more Pixel Agents relay servers via WebSocket.

Install

npm install -g @syv-ai/pixel-agents-watcher

Usage

Single office

pixel-agents-watcher --name "Alice" --server ws://relay-host:8080 --token secret

Or with npx (no install):

npx @syv-ai/pixel-agents-watcher --name "Alice" --server ws://relay-host:8080

Multiple offices

Create ~/.pixel-agents/offices.json:

{
  "name": "Alice",
  "palette": 2,
  "hueShift": 0,
  "phrases": ["lgtm", "shipping it!", "need coffee", "hmm..."],
  "offices": [
    { "id": "public", "url": "wss://public-office.example.com", "token": null, "enabled": true },
    { "id": "team", "url": "wss://team-office.example.com", "token": "secret", "enabled": true }
  ]
}

Then run:

pixel-agents-watcher --config ~/.pixel-agents/offices.json

If no --server or --config flag is given, the watcher checks ~/.pixel-agents/offices.json automatically. If the file doesn't exist, it falls back to single-office mode.

The config file is watched for live changes — add, remove, or toggle offices without restarting.

Options

| Flag | Default | Description | |------|---------|-------------| | --name <name> | Unknown | Your display name in the office | | --server <url> | ws://localhost:8080 | Single relay server URL | | --token <token> | (none) | Authentication token (single-office mode) | | --palette <0-5> | (none) | Character palette index | | --hue-shift <deg> | (none) | Character hue shift in degrees | | --phrases <list> | (none) | Comma-separated phrases agents may say (e.g. "lgtm,shipping it!") | | --config <path> | (none) | Path to offices.json (multi-office mode) | | --help, -h | | Show help | | --version, -v | | Show version |

How it works

1. Watches ~/.claude/projects/ for JSONL transcript files
2. Detects recently active sessions (modified in last 10 minutes)
3. Parses tool_use/tool_result events from Claude Code transcripts
4. Streams status labels (e.g., "Reading", "Editing") to all connected relay servers — no tool input/output data leaves the machine
5. Auto-reconnects on disconnect (per-office, independent)

Requirements

• Node.js >= 18
• Claude Code writing JSONL transcripts to ~/.claude/projects/

Credits

Built on top of Pixel Agents by Pablo De Lucca — the original pixel art office for AI agents.

License

MIT