@caglarutkuguler/cubicle 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Çağlar Utku Güler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# Cubicle
+
+**A live pixel-art office for your AI agents.** Works with [Paperclip](https://github.com/paperclipai/paperclip), [Claude Code](https://claude.com/claude-code), or any tool that can write a small JSON file.
+
+**[▶ Live demo](https://caglarutkuguler.github.io/cubicle/?lang=en)** — no install, fake agents.
+
+Your agents get a desk. When one starts working it walks over, sits down and starts typing, with its current task floating above its head. When it needs you, it raises a hand. When it finishes it goes back to the lounge for a coffee. If it hits an error, its screen flashes red.
+
+[![Cubicle demo](docs/demo.gif)](https://caglarutkuguler.github.io/cubicle/?lang=en)
+
+- **Zero dependencies.** One small Node.js file plus one HTML page. No build step, no image assets.
+- **Read-only by design.** Cubicle only ever makes `GET` requests, and only to a short allowlist. It cannot change anything in your agent system.
+- **Not tied to one platform.** Paperclip and Claude Code are built in; anything else plugs in through a [tiny JSON feed](docs/FEED.md).
+- **Runs anywhere Node runs.** `npx`, a clone, a systemd unit, or a browser tab pointed at the hosted demo.
+- **English and Turkish UI**, picked from your browser language or with `?lang=en` / `?lang=tr`.
+
+## Quick start
+
+Requires Node.js 18+.
+
+**Paperclip** (default; expects Paperclip at `http://127.0.0.1:3100`):
+
+```bash
+npx github:caglarutkuguler/cubicle
+```
+
+**Claude Code** (one character per session, driven by Claude Code's own hooks; details in [`examples/claude-code/`](examples/claude-code/)):
+
+```bash
+npx github:caglarutkuguler/cubicle install-hooks      # once; backs up ~/.claude/settings.json first
+npx github:caglarutkuguler/cubicle --source claude-code
+```
+
+**Anything else** — a JSON file or URL in the [feed format](docs/FEED.md):
+
+```bash
+npx github:caglarutkuguler/cubicle --source ./agents.json
+npx github:caglarutkuguler/cubicle --source http://localhost:8080/agents
+```
+
+Then open <http://127.0.0.1:3200>. Nothing running yet? Open <http://127.0.0.1:3200/?demo>, or the [hosted demo](https://caglarutkuguler.github.io/cubicle/?lang=en).
+
+Or from a clone:
+
+```bash
+git clone https://github.com/caglarutkuguler/cubicle.git
+cd cubicle
+node bin/cubicle.js            # add --source … as above
+```
+
+## Options
+
+| Flag | Environment variable | Default |
+| --- | --- | --- |
+| `--port` | `CUBICLE_PORT` | `3200` |
+| `--host` | `CUBICLE_HOST` | `127.0.0.1` |
+| `--source` | `CUBICLE_SOURCE` | `paperclip` — or `claude-code`, a `.json` file, or an `http(s)://` URL |
+| `--paperclip` | `PAPERCLIP_URL` | `http://127.0.0.1:3100` |
+| `--token-file` | `PAPERCLIP_TOKEN` / `PAPERCLIP_TOKEN_FILE` | none — API key for an authenticated Paperclip |
+
+URL parameters:
+
+- `?company=PREFIX` opens a specific Paperclip company (for example `?company=MEG`). With several companies, a picker also appears in the header.
+- `?lang=en` or `?lang=tr` sets the language.
+- `?demo` shows fake agents.
+
+## What the office shows
+
+| Status | In the office |
+| --- | --- |
+| `running` | Sits at its desk, monitor on, typing; bubble shows the task |
+| `waiting` | Sits at its desk with a hand up, amber screen — it needs your input or approval |
+| `idle` | Wanders the lounge; says "✓ done" right after finishing a run |
+| `error` | Slumped at its desk, red screen, error text on its card |
+| `paused` | "zZ" |
+
+Each card below the office links to the agent's current task when the source provides a link (Paperclip issues do).
+
+## Sources
+
+**Paperclip.** Cubicle proxies three read-only endpoints (`/api/health`, `/api/companies`, `/api/companies/:id/agents|issues`) and maps Paperclip's agent status and open issues onto the office. Any adapter Paperclip supports — Claude Code, Codex, Cursor, HTTP agents — shows up, because the status comes from Paperclip itself.
+
+The default `local_trusted` mode needs no key. For an authenticated or remote Paperclip, give Cubicle an API key; it is sent as `Authorization: Bearer …` on the forwarded requests only:
+
+```bash
+PAPERCLIP_URL=https://paperclip.example.com PAPERCLIP_TOKEN=pcp_… npx github:caglarutkuguler/cubicle
+# or keep it in a file only you can read
+npx github:caglarutkuguler/cubicle --paperclip https://paperclip.example.com --token-file ~/.config/cubicle/paperclip-token
+```
+
+Use a board API key with the narrowest read-only scope Paperclip lets you create; an agent key also works but only sees that agent's company. There is no `--token` flag on purpose, because command-line flags are visible in the process list. With systemd, put `PAPERCLIP_TOKEN=…` in a `chmod 600` file and point `EnvironmentFile=` at it (see `examples/systemd/cubicle.service`).
+
+**Claude Code.** A hook script ([`bin/cubicle-hook.js`](bin/cubicle-hook.js)) runs on Claude Code's own hook events and rewrites `~/.cubicle/claude-code.json`. Tool calls put the character at its desk, permission prompts raise its hand, `Stop` sends it to the lounge. Setup and privacy notes: [`examples/claude-code/README.md`](examples/claude-code/README.md).
+
+**Feed.** Any process can write `{ "company": "…", "agents": [{ "id", "name", "role", "status", "task", "error" }] }` to a file or serve it over HTTP. Full spec with status aliases: [`docs/FEED.md`](docs/FEED.md). A sample is in [`examples/feed.json`](examples/feed.json).
+
+## Run it as a service (Linux / WSL)
+
+systemd user units are in [`examples/systemd/`](examples/systemd/): `cubicle.service` (Paperclip, port 3200), `cubicle-claude.service` (Claude Code, port 3201), and an optional updater.
+
+```bash
+git clone https://github.com/caglarutkuguler/cubicle.git ~/cubicle
+mkdir -p ~/.config/systemd/user
+cp ~/cubicle/examples/systemd/*.service ~/cubicle/examples/systemd/*.timer ~/.config/systemd/user/
+# edit ExecStart in cubicle*.service to point at your node binary (`command -v node`)
+systemctl --user daemon-reload
+systemctl --user enable --now cubicle.service cubicle-claude.service
+```
+
+**Stay up to date automatically.** `cubicle-update.timer` fast-forwards the clone every 10 minutes and restarts the running Cubicle services when something changed; open browser tabs reload themselves within a minute. It never touches a clone with local edits.
+
+```bash
+# link instead of copying, so updates to these two units arrive with the clone
+systemctl --user link ~/cubicle/examples/systemd/cubicle-update.service ~/cubicle/examples/systemd/cubicle-update.timer
+systemctl --user enable --now cubicle-update.timer
+journalctl --user -u cubicle-update.service   # what it did
+```
+
+## Security notes
+
+- Cubicle binds to `127.0.0.1` by default. Keep it that way unless you put it behind your own authentication, because anyone who can reach it can see your agent names, statuses and task titles.
+- Only `GET` and `HEAD` are accepted; everything else gets `405`. In Paperclip mode only the three endpoints above are forwarded and any other `/api/` path gets `403`. In feed mode the only upstream request is a `GET` to the configured file or URL.
+- A Paperclip API key is added by the proxy and never sent to the browser. The browser's own cookies and `Authorization` header are never forwarded upstream. If you bind to anything other than loopback while a key is set, Cubicle prints a warning at startup: everyone who can reach the port can read what the key can read.
+- The Claude Code hook never touches the network and stores only session id, directory name, status and a short summary of the current tool call.
+
+## How it works
+
+`bin/cubicle.js` serves `public/index.html` and either proxies the allowed Paperclip endpoints or serves the feed at `/api/feed`. The page polls every 4 seconds and draws everything, including characters, furniture and the day/night windows, on a 352×208 canvas with plain rectangles.
+
+## Contributing
+
+Issues and pull requests are welcome. Ideas: adapters for other agent runtimes (write a feed, send a PR with an example), a kiosk mode for wall displays, meeting-room animations when agents hand work to each other, per-agent sprite customisation, replay of a recorded day, and multi-source offices (Paperclip and Claude Code on one floor).
+
+## Credits
+
+Inspired by the idea behind [Pixel Agents](https://github.com/pixel-agents-hq/pixel-agents) by Pablo De Lucca. Cubicle is an independent implementation and uses no code or assets from it.
+
+Cubicle is a community project and is not affiliated with or endorsed by Paperclip Labs or Anthropic.
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+### Türkçe
+
+**Cubicle**, AI ajanlarınızı canlı bir pixel ofiste gösterir: [Paperclip](https://github.com/paperclipai/paperclip) ve Claude Code hazır gelir; başka sistemler küçük bir [JSON feed](docs/FEED.md) ile bağlanır. Çalışan ajan masasına oturup yazar ve başının üstünde görevi görünür; sizi bekleyen ajan elini kaldırır; işi biten ajan dinlenme alanına döner; hata alan ajanın ekranı kırmızı yanar.
+
+Kurulum: `npx github:caglarutkuguler/cubicle` (Paperclip) veya `npx github:caglarutkuguler/cubicle --source claude-code` (Claude Code) çalıştırın ve <http://127.0.0.1:3200> adresini açın. Kurmadan denemek için: [canlı demo](https://caglarutkuguler.github.io/cubicle/?lang=tr). Arayüz tarayıcı diline göre Türkçe açılır; `?lang=tr` ile de seçilebilir.

package/bin/cubicle-hook.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// Cubicle hook for Claude Code.
+// Claude Code runs this on hook events and pipes the event JSON to stdin.
+// It keeps ~/.cubicle/claude-code.json up to date, one agent per session,
+// in the Cubicle feed format (docs/FEED.md). No dependencies, no network.
+//
+// Wire it up with the snippet in examples/claude-code/settings.json, then run:
+//   cubicle --source claude-code
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DIR = path.join(os.homedir(), '.cubicle');
+const FILE = path.join(DIR, 'claude-code.json');
+const STALE_MS = 12 * 60 * 60 * 1000; // drop sessions with no event for 12 h
+
+function summarize(ev) {
+  const tool = ev.tool_name || '';
+  const inp = ev.tool_input || {};
+  const short = (s, n = 48) => { s = String(s || '').replace(/\s+/g, ' ').trim(); return s.length > n ? s.slice(0, n - 1) + '…' : s; };
+  if (inp.file_path) return `${tool} ${path.basename(inp.file_path)}`;
+  if (inp.command) return `${tool}: ${short(inp.command)}`;
+  if (inp.description) return `${tool}: ${short(inp.description)}`;
+  if (inp.pattern) return `${tool} ${short(inp.pattern, 30)}`;
+  if (inp.query) return `${tool}: ${short(inp.query)}`;
+  return tool || 'working';
+}
+
+function apply(feed, ev) {
+  const id = ev.session_id || 'unknown';
+  const now = Date.now();
+  const agents = feed.agents.filter((a) => now - (a.updated || 0) < STALE_MS);
+  let a = agents.find((x) => x.id === id);
+  const name = path.basename(ev.cwd || '') || 'claude';
+
+  switch (ev.hook_event_name) {
+    case 'SessionEnd':
+      return { ...feed, agents: agents.filter((x) => x.id !== id) };
+    case 'SessionStart':
+      a = a || { id, since: now };
+      Object.assign(a, { name, role: 'Claude Code', status: 'idle', task: null, error: null });
+      break;
+    case 'UserPromptSubmit':
+      a = a || { id, since: now, name, role: 'Claude Code' };
+      Object.assign(a, { status: 'running', task: summarizePrompt(ev.prompt), error: null });
+      break;
+    case 'PreToolUse':
+    case 'PostToolUse':
+    case 'PreCompact':
+      a = a || { id, since: now, name, role: 'Claude Code' };
+      Object.assign(a, { status: 'running', task: ev.hook_event_name === 'PreCompact' ? 'compacting context' : summarize(ev), error: null });
+      break;
+    case 'PermissionRequest':
+      a = a || { id, since: now, name, role: 'Claude Code' };
+      Object.assign(a, { status: 'waiting', task: ev.tool_name ? `allow ${summarize(ev)}?` : 'needs your permission' });
+      break;
+    case 'Notification':
+      // Only notifications that ask the user for something raise a hand.
+      // idle_prompt (~60 s after a turn), auth_success, agent_completed, quota_* etc. are ignored.
+      if (!needsUser(ev)) return feed;
+      a = a || { id, since: now, name, role: 'Claude Code' };
+      Object.assign(a, { status: 'waiting', task: ev.message ? String(ev.message).slice(0, 80) : 'needs your input' });
+      break;
+    case 'StopFailure':
+      a = a || { id, since: now, name, role: 'Claude Code' };
+      Object.assign(a, { status: 'error', error: String(ev.error || ev.message || 'turn failed').slice(0, 120) });
+      break;
+    case 'Stop':
+      a = a || { id, since: now, name, role: 'Claude Code' };
+      Object.assign(a, { status: 'idle', task: null });
+      break;
+    default:
+      return feed; // SubagentStop etc.: nothing to draw
+  }
+  a.updated = now;
+  if (!agents.includes(a)) agents.push(a);
+  return { ...feed, agents };
+}
+
+const ASKS_USER = new Set(['permission_prompt', 'agent_needs_input', 'elicitation_dialog', 'elicitation_url_dialog']);
+function needsUser(ev) {
+  if (ev.notification_type) return ASKS_USER.has(ev.notification_type);
+  // Older Claude Code versions send no type; fall back to the message text.
+  const m = String(ev.message || '');
+  return /permission|needs your|approve/i.test(m) && !/waiting for your input/i.test(m);
+}
+
+function summarizePrompt(p) {
+  p = String(p || '').replace(/\s+/g, ' ').trim();
+  return p ? (p.length > 60 ? p.slice(0, 59) + '…' : p) : 'thinking';
+}
+
+function main() {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (d) => { input += d; });
+  process.stdin.on('end', () => {
+    let ev;
+    try { ev = JSON.parse(input || '{}'); } catch (_) { return; }
+    // A visualisation must never get in Claude's way: swallow every error, exit 0.
+    try {
+      let feed = { company: 'Claude Code', agents: [] };
+      try { const cur = JSON.parse(fs.readFileSync(FILE, 'utf8')); if (Array.isArray(cur.agents)) feed = cur; } catch (_) {}
+      feed = apply(feed, ev);
+      fs.mkdirSync(DIR, { recursive: true });
+      const tmp = `${FILE}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(feed));
+      fs.renameSync(tmp, FILE); // atomic on the same filesystem
+    } catch (_) {}
+  });
+}
+
+// ---------- install / uninstall into Claude Code settings ----------
+const EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PermissionRequest', 'PostToolUse',
+  'Notification', 'PreCompact', 'Stop', 'StopFailure', 'SessionEnd'];
+const isOurs = (h) => /cubicle-hook\.js|cubicle"? hook\b/.test(String(h && h.command));
+
+function install({ uninstall = false, settingsFile = path.join(os.homedir(), '.claude', 'settings.json') } = {}) {
+  let settings = {};
+  let existed = false;
+  try { settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8')); existed = true; }
+  catch (e) { if (e.code !== 'ENOENT') throw new Error(`cannot parse ${settingsFile}: ${e.message}`); }
+
+  const hooks = settings.hooks || {};
+  // Drop any earlier Cubicle entries so the result is the same however often this runs.
+  for (const ev of Object.keys(hooks)) {
+    hooks[ev] = (hooks[ev] || [])
+      .map((grp) => ({ ...grp, hooks: (grp.hooks || []).filter((h) => !isOurs(h)) }))
+      .filter((grp) => grp.hooks.length);
+    if (!hooks[ev].length) delete hooks[ev];
+  }
+  if (!uninstall) {
+    const command = `node "${path.resolve(__filename)}"`;
+    for (const ev of EVENTS) (hooks[ev] = hooks[ev] || []).push({ hooks: [{ type: 'command', command, timeout: 5 }] });
+  }
+  if (Object.keys(hooks).length) settings.hooks = hooks; else delete settings.hooks;
+
+  fs.mkdirSync(path.dirname(settingsFile), { recursive: true });
+  if (existed) {
+    const backup = `${settingsFile}.bak-cubicle-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    fs.copyFileSync(settingsFile, backup);
+    console.log(`Backed up ${settingsFile} to ${backup}`);
+  }
+  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+  console.log(uninstall
+    ? `Removed Cubicle hooks from ${settingsFile}.`
+    : `Added Cubicle hooks for ${EVENTS.length} events to ${settingsFile}.\nStart the office with: cubicle --source claude-code  (then open http://127.0.0.1:3200)\nRunning Claude Code sessions pick the hooks up after a restart.`);
+}
+
+if (require.main === module) main();
+module.exports = { apply, summarize, main, install, EVENTS };

package/bin/cubicle.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// Cubicle — a live pixel-art office for your AI agents.
+// A tiny, dependency-free, read-only proxy + static page.
+//
+// Sources:
+//   paperclip (default)  read agents/issues from a Paperclip server
+//   claude-code          read the feed written by examples/claude-code/cubicle-hook.js
+//   <file.json>          read a Cubicle feed from a JSON file (see docs/FEED.md)
+//   <http(s)://url>      read a Cubicle feed from a URL (GET only)
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : undefined;
+}
+
+// `cubicle hook` — used from Claude Code hooks; see examples/claude-code/.
+if (process.argv[2] === 'hook') {
+  require('./cubicle-hook.js').main();
+  return;
+}
+// `cubicle install-hooks [--uninstall]` — add/remove the Claude Code hooks in ~/.claude/settings.json.
+if (process.argv[2] === 'install-hooks') {
+  try { require('./cubicle-hook.js').install({ uninstall: process.argv.includes('--uninstall') }); }
+  catch (e) { console.error(e.message); process.exitCode = 1; }
+  return;
+}
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`Cubicle — a live pixel-art office for your AI agents
+
+Usage: cubicle [--port 3200] [--host 127.0.0.1] [--source paperclip] [--paperclip http://127.0.0.1:3100] [--token-file FILE]
+       cubicle install-hooks [--uninstall]   add/remove the Claude Code hooks in ~/.claude/settings.json
+
+Sources (--source / CUBICLE_SOURCE):
+  paperclip            Paperclip server, default (see --paperclip / PAPERCLIP_URL)
+  claude-code          Claude Code sessions, via the hook in examples/claude-code/
+  ./agents.json        Any JSON file in the Cubicle feed format (docs/FEED.md)
+  http://host/feed     Any URL returning the Cubicle feed format
+
+Environment variables:
+  CUBICLE_PORT     Port to listen on (default 3200)
+  CUBICLE_HOST     Interface to bind (default 127.0.0.1)
+  CUBICLE_SOURCE   Source, as above (default paperclip)
+  PAPERCLIP_URL    Paperclip server URL (default http://127.0.0.1:3100)
+  PAPERCLIP_TOKEN  API key for an authenticated Paperclip, sent as "Authorization: Bearer …"
+                   (or put it in a file and pass --token-file / PAPERCLIP_TOKEN_FILE).
+                   There is deliberately no --token flag: flags show up in the process list.
+`);
+  process.exit(0);
+}
+
+const PORT = Number(arg('port') || process.env.CUBICLE_PORT || 3200);
+const HOST = arg('host') || process.env.CUBICLE_HOST || '127.0.0.1';
+const PAPERCLIP = new URL(arg('paperclip') || process.env.PAPERCLIP_URL || 'http://127.0.0.1:3100');
+const PUBLIC_DIR = path.join(__dirname, '..', 'public');
+const VERSION = require('../package.json').version;
+const STARTED = Date.now();
+// Changes when the server restarts or index.html changes on disk; open pages
+// compare it and reload themselves, so a wall display picks up updates.
+function build() {
+  let mtime = 0;
+  try { mtime = fs.statSync(path.join(PUBLIC_DIR, 'index.html')).mtimeMs; } catch (_) {}
+  return `${VERSION}-${STARTED}-${Math.round(mtime)}`;
+}
+const CLAUDE_CODE_FEED = path.join(os.homedir(), '.cubicle', 'claude-code.json');
+
+// ---------- Paperclip credentials ----------
+// Added by the proxy only; never sent to the browser, never taken from the browser.
+function readToken() {
+  const file = arg('token-file') || process.env.PAPERCLIP_TOKEN_FILE;
+  if (file) {
+    try { return fs.readFileSync(file, 'utf8').trim(); }
+    catch (e) { console.error(`Cannot read token file ${file}: ${e.message}`); process.exit(1); }
+  }
+  return (process.env.PAPERCLIP_TOKEN || '').trim();
+}
+const TOKEN = readToken();
+if (TOKEN && !/^[\x21-\x7e]+$/.test(TOKEN)) {
+  console.error('The Paperclip API key contains spaces or control characters; check PAPERCLIP_TOKEN / the token file.');
+  process.exit(1);
+}
+
+// ---------- source ----------
+const rawSource = arg('source') || process.env.CUBICLE_SOURCE || 'paperclip';
+let source; // { kind: 'paperclip' } | { kind: 'file', file, label } | { kind: 'url', url, label }
+if (rawSource === 'paperclip') source = { kind: 'paperclip' };
+else if (rawSource === 'claude-code') source = { kind: 'file', file: CLAUDE_CODE_FEED, label: 'Claude Code', emptyIfMissing: true };
+else if (/^https?:\/\//.test(rawSource)) source = { kind: 'url', url: new URL(rawSource), label: rawSource };
+else source = { kind: 'file', file: path.resolve(rawSource), label: path.basename(rawSource) };
+
+function get(url, cb, extraHeaders = {}) {
+  const client = url.protocol === 'https:' ? https : http;
+  const req = client.get(
+    { protocol: url.protocol, hostname: url.hostname, port: url.port, path: url.pathname + url.search, headers: { accept: 'application/json', ...extraHeaders }, timeout: 10000 },
+    cb
+  );
+  req.on('timeout', () => req.destroy(new Error('timeout')));
+  return req;
+}
+
+// Only these read-only Paperclip endpoints are ever forwarded.
+const ALLOWED = [
+  /^\/api\/health$/,
+  /^\/api\/companies$/,
+  /^\/api\/companies\/[\w-]+\/(agents|issues)$/,
+];
+
+function send(res, status, body, type = 'application/json') {
+  res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store' });
+  res.end(body);
+}
+
+function serveFeed(res) {
+  if (source.kind === 'file') {
+    return fs.readFile(source.file, 'utf8', (err, txt) => {
+      // No hook has fired yet: that is an empty office, not an error.
+      if (err && err.code === 'ENOENT' && source.emptyIfMissing) return send(res, 200, JSON.stringify({ company: source.label, agents: [] }));
+      if (err) return send(res, err.code === 'ENOENT' ? 404 : 500, JSON.stringify({ error: `cannot read ${source.file}` }));
+      try { JSON.parse(txt); } catch (_) { return send(res, 502, '{"error":"feed is not valid JSON"}'); }
+      send(res, 200, txt);
+    });
+  }
+  const upstream = get(source.url, (r) => {
+    res.writeHead(r.statusCode, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+    r.pipe(res);
+  });
+  upstream.on('error', () => send(res, 502, '{"error":"feed unreachable"}'));
+}
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url, 'http://localhost');
+
+  if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, '{"error":"read-only"}');
+
+  if (url.pathname === '/config.json') {
+    const cfg = source.kind === 'paperclip'
+      ? { source: 'paperclip', paperclipUrl: PAPERCLIP.origin, version: VERSION, build: build() }
+      : { source: 'feed', label: source.label, version: VERSION, build: build() };
+    return send(res, 200, JSON.stringify(cfg));
+  }
+
+  if (url.pathname === '/api/feed') {
+    if (source.kind === 'paperclip') return send(res, 404, '{"error":"no feed source configured"}');
+    return serveFeed(res);
+  }
+
+  if (url.pathname.startsWith('/api/')) {
+    if (source.kind !== 'paperclip') return send(res, 403, '{"error":"not allowed"}');
+    if (!ALLOWED.some((re) => re.test(url.pathname))) return send(res, 403, '{"error":"not allowed"}');
+    const upstream = get(new URL(url.pathname, PAPERCLIP), (r) => {
+      res.writeHead(r.statusCode, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      r.pipe(res);
+    }, TOKEN ? { authorization: `Bearer ${TOKEN}` } : {});
+    upstream.on('error', () => send(res, 502, '{"error":"paperclip unreachable"}'));
+    return;
+  }
+
+  if (url.pathname === '/' || url.pathname === '/index.html') {
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+    return fs.createReadStream(path.join(PUBLIC_DIR, 'index.html')).pipe(res);
+  }
+
+  send(res, 404, 'Not found', 'text/plain');
+});
+
+server.listen(PORT, HOST, () => {
+  const reading = source.kind === 'paperclip' ? PAPERCLIP.origin : source.kind === 'file' ? source.file : source.url.href;
+  console.log(`Cubicle is open at http://${HOST}:${PORT}  (reading ${reading}${source.kind === 'paperclip' && TOKEN ? ' with an API key' : ''})`);
+  const loopback = ['127.0.0.1', 'localhost', '::1'].includes(HOST);
+  if (source.kind === 'paperclip' && TOKEN && !loopback) {
+    console.warn(`Warning: bound to ${HOST} with a Paperclip API key. Anyone who can reach this port can read what that key can read.`);
+  }
+  if (source.kind === 'paperclip') console.log(`No Paperclip yet? Try the demo: http://${HOST}:${PORT}/?demo`);
+});

package/docs/FEED.md

@@ -0,0 +1,59 @@
+# Cubicle feed format
+
+Cubicle can show agents from any system that can produce this JSON. Point it at a file or a URL:
+
+```bash
+cubicle --source ./agents.json
+cubicle --source http://localhost:8080/agents
+```
+
+The file is re-read (or the URL re-fetched) every 4 seconds. Only `GET` is ever made; Cubicle never writes to the source.
+
+## Shape
+
+```json
+{
+  "company": "Acme Bots",
+  "agents": [
+    { "id": "writer",  "name": "Writer",  "role": "Copywriter", "status": "running", "task": { "id": "DOC-12", "title": "Draft launch post", "url": "https://example.com/DOC-12" } },
+    { "id": "qa",      "name": "QA",      "status": "waiting", "task": "Approve deploy to staging?" },
+    { "id": "scraper", "name": "Scraper", "status": "error",   "error": "HTTP 429 from target site" },
+    { "id": "intern",  "name": "Intern",  "status": "idle" }
+  ]
+}
+```
+
+A bare array of agents is accepted too.
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `id` | yes | Stable identifier; the character keeps its look and desk while the id stays the same. Falls back to `name`. |
+| `name` | yes | Shown above the character and on the card. |
+| `role` | no | Shown on the card. |
+| `status` | yes | One of `running`, `idle`, `error`, `paused`, `waiting`. Aliases: `working`/`busy`/`active` → running; `done`/`finished` → idle; `failed` → error; `sleeping`/`stopped`/`offline` → paused; `blocked`/`needs_input`/`permission` → waiting. Unknown values count as idle. |
+| `task` | no | A string, or `{ "id", "title", "url" }`. Shown in the bubble while typing and on the card; `url` makes it a link. |
+| `error` | no | Text shown on the card when `status` is `error`. |
+| `since` | no | Creation timestamp (any sortable value). Decides desk order; defaults to array order. |
+| `company` | no | Top-level; shown in the header. |
+
+## Status → behaviour
+
+| Status | In the office |
+| --- | --- |
+| `running` | At the desk, monitor on, typing; bubble shows the task |
+| `waiting` | At the desk, hand up, amber blinking monitor; bubble "✋ needs you" |
+| `error` | Slumped at the desk, red flashing monitor; error text on the card |
+| `idle` | Wanders the lounge; "✓ done" right after a run |
+| `paused` | In the lounge, "zZ" |
+
+## Writing a feed from a script
+
+Any language works. Write to a temp file and rename it so Cubicle never reads a half-written file:
+
+```python
+import json, os
+feed = {"company": "My crew", "agents": [{"id": "a1", "name": "Alpha", "status": "running", "task": "Indexing"}]}
+with open("agents.json.tmp", "w") as f:
+    json.dump(feed, f)
+os.replace("agents.json.tmp", "agents.json")
+```

package/examples/claude-code/README.md

@@ -0,0 +1,38 @@
+# Cubicle for Claude Code
+
+Every Claude Code session becomes one character in the office. It sits down and types while Claude is calling tools, raises a hand when Claude is waiting for your permission or input, and heads to the lounge when the turn is over.
+
+No daemon, no sockets: Claude Code's own hooks run a small script that rewrites `~/.cubicle/claude-code.json`, and Cubicle reads that file.
+
+## Setup
+
+```bash
+git clone https://github.com/caglarutkuguler/cubicle.git ~/cubicle
+node ~/cubicle/bin/cubicle.js install-hooks          # adds the hooks to ~/.claude/settings.json (backup first)
+node ~/cubicle/bin/cubicle.js --source claude-code   # then open http://127.0.0.1:3200
+```
+
+`install-hooks` keeps everything else in your settings, can be run again safely, and `install-hooks --uninstall` removes only Cubicle's entries. Restart running Claude Code sessions so they load the hooks.
+
+Prefer to edit by hand? Merge [`settings.json`](settings.json) from this folder into `~/.claude/settings.json` (user-wide) or `.claude/settings.json` (one project), replacing `/path/to/cubicle`.
+
+To keep it running in the background next to a Paperclip office, see [`../systemd/`](../systemd/): `cubicle-claude.service` serves the Claude Code office on port 3201.
+
+## What maps to what
+
+| Claude Code event | In the office |
+| --- | --- |
+| `UserPromptSubmit`, `PreToolUse`, `PostToolUse` | Sits at the desk and types; the bubble shows the tool and file/command |
+| `PermissionRequest`, `Notification` of type `permission_prompt` / `agent_needs_input` / `elicitation_*` | Stays at the desk with a hand up, amber screen |
+| `Stop` | Says "✓ done" and goes to the lounge |
+| `StopFailure` | Red screen, error on the card |
+| `SessionEnd` | Leaves the office |
+
+Other notifications — the "waiting for your input" reminder after a minute of idling, auth and quota messages — are ignored, so an idle session stays in the lounge.
+
+The character is named after the working directory, so two sessions in different repos are easy to tell apart. Sessions with no events for 12 hours are dropped.
+
+## Cost and safety
+
+- Each hook is one short `node` process (tens of milliseconds) with a 5 s timeout. It never exits with code 2, so it can never block a tool call, and it prints nothing, so it adds nothing to Claude's context.
+- The hook writes only: session id, directory name, status, and a short summary of the current tool call (tool name plus file name or the first ~50 characters of a command or prompt). Nothing leaves the machine.

package/examples/claude-code/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart":      [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }],
+    "UserPromptSubmit":  [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }],
+    "PreToolUse":        [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }],
+    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }],
+    "PostToolUse":       [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }],
+    "Notification":      [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }],
+    "PreCompact":        [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }],
+    "Stop":              [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }],
+    "StopFailure":       [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }],
+    "SessionEnd":        [{ "hooks": [{ "type": "command", "command": "node \"/path/to/cubicle/bin/cubicle-hook.js\"", "timeout": 5 }] }]
+  }
+}

package/examples/feed.json

@@ -0,0 +1,9 @@
+{
+  "company": "Acme Bots",
+  "agents": [
+    { "id": "writer", "name": "Writer", "role": "Copywriter", "status": "running", "task": { "id": "DOC-12", "title": "Draft launch post", "url": "https://example.com/DOC-12" } },
+    { "id": "qa", "name": "QA", "role": "Release", "status": "waiting", "task": "Approve deploy to staging?" },
+    { "id": "scraper", "name": "Scraper", "role": "Data", "status": "error", "error": "HTTP 429 from target site" },
+    { "id": "intern", "name": "Intern", "status": "idle" }
+  ]
+}

package/examples/systemd/cubicle-claude.service

@@ -0,0 +1,12 @@
+[Unit]
+Description=Cubicle - live pixel office for Claude Code sessions
+
+[Service]
+# Adjust both paths: your node binary and your Cubicle clone
+ExecStart=/usr/bin/node %h/cubicle/bin/cubicle.js --source claude-code
+Environment=CUBICLE_PORT=3201
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=default.target

package/examples/systemd/cubicle-update.service

@@ -0,0 +1,9 @@
+[Unit]
+Description=Update the Cubicle clone and restart Cubicle services if it changed
+After=network-online.target
+
+[Service]
+Type=oneshot
+# Adjust the path if your clone is not in ~/cubicle
+Environment=CUBICLE_DIR=%h/cubicle
+ExecStart=/bin/bash %h/cubicle/examples/systemd/cubicle-update.sh

package/examples/systemd/cubicle-update.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Keep a Cubicle clone up to date and restart its running services when it changes.
+# Run by cubicle-update.timer; safe to run by hand.
+#
+# - Only fast-forwards. If the clone has local edits or has diverged, it does nothing.
+# - Restarts every active cubicle*.service (except the updater itself) after an update.
+#   Open browser tabs notice the restart and reload themselves within a minute.
+set -euo pipefail
+
+DIR="${CUBICLE_DIR:-$HOME/cubicle}"
+cd "$DIR"
+
+if [ -n "$(git status --porcelain --untracked-files=no)" ]; then
+  echo "cubicle-update: local changes in $DIR, skipping"
+  exit 0
+fi
+
+branch="$(git rev-parse --abbrev-ref HEAD)"
+before="$(git rev-parse HEAD)"
+git fetch --quiet origin "$branch"
+if ! git merge --ff-only --quiet "origin/$branch" 2>/dev/null; then
+  echo "cubicle-update: cannot fast-forward $branch, skipping"
+  exit 0
+fi
+after="$(git rev-parse HEAD)"
+[ "$before" = "$after" ] && exit 0
+
+echo "cubicle-update: $before -> $after"
+git --no-pager log --oneline "$before..$after"
+
+# Unit files symlinked from this clone may have changed too.
+systemctl --user daemon-reload
+
+systemctl --user list-units --type=service --state=active --no-legend --plain 'cubicle*.service' \
+  | awk '{print $1}' \
+  | grep -v '^cubicle-update\.service$' \
+  | while read -r unit; do
+      echo "cubicle-update: restarting $unit"
+      systemctl --user restart "$unit"
+    done

package/examples/systemd/cubicle-update.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Check for Cubicle updates every 10 minutes
+
+[Timer]
+OnCalendar=*:0/10
+RandomizedDelaySec=60
+Persistent=true
+
+[Install]
+WantedBy=timers.target

package/examples/systemd/cubicle.service

@@ -0,0 +1,16 @@
+[Unit]
+Description=Cubicle - live pixel office for Paperclip agents
+After=paperclipai.service
+
+[Service]
+# Adjust both paths: your node binary and your Cubicle clone
+ExecStart=/usr/bin/node %h/cubicle/bin/cubicle.js
+Environment=CUBICLE_PORT=3200
+Environment=PAPERCLIP_URL=http://127.0.0.1:3100
+# Authenticated Paperclip: a chmod 600 file containing the line PAPERCLIP_TOKEN=pcp_...
+# EnvironmentFile=%h/.config/cubicle/env
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=default.target

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@caglarutkuguler/cubicle",
+  "version": "0.3.0",
+  "description": "A live pixel-art office for your AI agents — Paperclip, Claude Code, or any JSON feed. Zero dependencies, read-only.",
+  "bin": {
+    "cubicle": "bin/cubicle.js"
+  },
+  "scripts": {
+    "start": "node bin/cubicle.js",
+    "demo": "node bin/cubicle.js & sleep 1 && echo 'Open http://127.0.0.1:3200/?demo'",
+    "test": "node test/smoke.js"
+  },
+  "files": [
+    "bin",
+    "public",
+    "docs/FEED.md",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai-agents",
+    "agent-orchestration",
+    "paperclip",
+    "claude-code",
+    "codex",
+    "cursor",
+    "pixel-art",
+    "dashboard",
+    "visualization",
+    "office"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caglarutkuguler/cubicle.git"
+  },
+  "author": "Çağlar Utku Güler",
+  "license": "MIT",
+  "homepage": "https://caglarutkuguler.github.io/cubicle/",
+  "bugs": {
+    "url": "https://github.com/caglarutkuguler/cubicle/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/public/index.html

@@ -0,0 +1,512 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Cubicle</title>
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Crect width='16' height='16' rx='3' fill='%23222536'/%3E%3Crect x='3' y='3' width='10' height='6' fill='%235cc8f0'/%3E%3Crect x='2' y='11' width='12' height='2' fill='%238b5a2b'/%3E%3C/svg%3E">
+<style>
+  :root { --bg:#171926; --panel:#222536; --line:#33374d; --text:#e9e7f2; --muted:#9a9bb3; --link:#9ec5ff; }
+  * { box-sizing: border-box; }
+  body { margin:0; background:var(--bg); color:var(--text); font:13px/1.45 system-ui, "Segoe UI", sans-serif; }
+  .wrap { max-width:1180px; margin:0 auto; padding:14px 16px 28px; }
+  header { display:flex; align-items:center; justify-content:space-between; gap:12px; flex-wrap:wrap; margin-bottom:10px; }
+  h1 { font-size:17px; margin:0; letter-spacing:.2px; }
+  h1 small { color:var(--muted); font-weight:500; margin-left:8px; }
+  .right { display:flex; align-items:center; gap:10px; color:var(--muted); }
+  select { background:var(--panel); color:var(--text); border:1px solid var(--line); border-radius:6px; padding:3px 6px; font:inherit; }
+  #stage { position:relative; width:100%; aspect-ratio:352/208; border:2px solid var(--line); border-radius:8px; overflow:hidden; background:#2a2d3d; }
+  canvas { position:absolute; inset:0; width:100%; height:100%; image-rendering:pixelated; }
+  #labels { position:absolute; inset:0; pointer-events:none; }
+  .lbl { position:absolute; transform:translate(-50%,-100%); display:flex; flex-direction:column; align-items:center; white-space:nowrap; }
+  .bub { background:#fff; color:#1d1f2b; border-radius:9px; padding:2px 7px; font-size:11px; font-weight:600; margin-bottom:3px; box-shadow:0 1px 0 rgba(0,0,0,.3); max-width:210px; overflow:hidden; text-overflow:ellipsis; }
+  .bub.err { background:#ffdede; color:#8a1111; }
+  .bub.ok { background:#dcffe2; color:#145c24; }
+  .bub.wait { background:#fff1c9; color:#6b4d00; }
+  .name { background:rgba(15,16,26,.78); color:#fff; font-size:11px; font-weight:600; padding:1px 6px; border-radius:5px; }
+  #banner { display:none; margin-bottom:10px; padding:8px 12px; border-radius:8px; background:#2b2f47; border:1px solid var(--line); color:var(--muted); }
+  #cards { display:grid; grid-template-columns:repeat(auto-fill,minmax(260px,1fr)); gap:8px; margin-top:12px; }
+  .card { background:var(--panel); border:1px solid var(--line); border-radius:8px; padding:9px 11px; }
+  .card .top { display:flex; align-items:center; gap:8px; }
+  .sw { width:12px; height:12px; border-radius:3px; flex:none; }
+  .card b { font-size:13px; }
+  .card .role { color:var(--muted); font-size:12px; }
+  .card .st { margin-top:4px; font-size:12px; }
+  a { color:var(--link); text-decoration:none; }
+  a:hover { text-decoration:underline; }
+  .pill { display:inline-block; font-size:11px; padding:0 6px; border-radius:9px; margin-right:6px; }
+  .p-running { background:#1f5130; color:#9ff0b4; }
+  .p-idle { background:#33374d; color:#c9cbe0; }
+  .p-error { background:#5a1f25; color:#ffb3b8; }
+  .p-paused { background:#4d4221; color:#f3dc92; }
+  .p-waiting { background:#5a4a12; color:#ffe08a; }
+  footer { color:var(--muted); font-size:12px; margin-top:12px; display:flex; justify-content:space-between; gap:12px; flex-wrap:wrap; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <h1>Cubicle <small id="co"></small></h1>
+    <div class="right">
+      <select id="company" hidden></select>
+      <span id="status"></span>
+    </div>
+  </header>
+  <div id="banner"></div>
+  <div id="stage">
+    <canvas id="c" width="352" height="208"></canvas>
+    <div id="labels"></div>
+  </div>
+  <div id="cards"></div>
+  <footer>
+    <span id="hint"></span>
+    <span><a href="https://github.com/caglarutkuguler/cubicle" target="_blank" rel="noopener">Cubicle</a> · MIT</span>
+  </footer>
+</div>
+
+<script>
+(() => {
+  // ---------- i18n ----------
+  const STR = {
+    en: {
+      connecting: 'Connecting…', unreachable: "Can't reach Paperclip, retrying…",
+      denied: (c) => `Paperclip refused access (${c}). Set PAPERCLIP_TOKEN for an authenticated Paperclip, or check the key.`, feedUnreachable: "Can't read the agent feed, retrying…",
+      empty: 'No agents yet.', emptyClaude: 'No Claude Code sessions yet — start <code>claude</code> in any folder and it will walk in.',
+      noCompany: 'No company yet.', summary: (n, r) => `${n} agents · ${r} working`,
+      running: 'working', idle: 'idle', error: 'error', paused: 'paused', waiting: 'needs you', noTask: 'no open task assigned',
+      done: '✓ done', errBubble: '⚠ error', waitBubble: '✋ needs you',
+      chatter: ['☕', 'coffee break', '…', 'hmm', "what's next?"],
+      hint: 'Working agents sit at their desks and type; idle agents hang out in the lounge. Refreshes every 4 s.',
+      demo: 'Demo mode — fake agents. Remove <code>?demo</code> from the URL to watch your own Paperclip company.',
+      hosted: 'This is the hosted demo with fake agents. To watch your own Paperclip company, run <code>npx github:caglarutkuguler/cubicle</code> and open <code>http://127.0.0.1:3200</code>.',
+    },
+    tr: {
+      connecting: 'Bağlanılıyor…', unreachable: "Paperclip'e ulaşılamıyor, yeniden deneniyor…",
+      denied: (c) => `Paperclip erişimi reddetti (${c}). Kimlik doğrulamalı Paperclip için PAPERCLIP_TOKEN tanımlayın veya anahtarı kontrol edin.`, feedUnreachable: 'Ajan verisi okunamıyor, yeniden deneniyor…',
+      empty: 'Henüz ajan yok.', emptyClaude: 'Henüz Claude Code oturumu yok. Herhangi bir klasörde <code>claude</code> başlatın, ofise girecek.',
+      noCompany: 'Henüz şirket yok.', summary: (n, r) => `${n} ajan · ${r} çalışıyor`,
+      running: 'çalışıyor', idle: 'boşta', error: 'hata', paused: 'duraklatıldı', waiting: 'sizi bekliyor', noTask: 'atanmış açık görev yok',
+      done: '✓ bitirdi', errBubble: '⚠ hata', waitBubble: '✋ sizi bekliyor',
+      chatter: ['☕', 'kahve molası', '…', 'hmm', 'sıradaki iş?'],
+      hint: 'Çalışan ajan masasına oturup yazar; boştaki ajan dinlenme alanında dolaşır. 4 saniyede bir yenilenir.',
+      demo: "Demo modu: sahte ajanlar. Kendi Paperclip şirketinizi izlemek için adresten <code>?demo</code> kısmını kaldırın.",
+      hosted: "Bu, sahte ajanlarla çalışan barındırılan demo. Kendi Paperclip şirketinizi izlemek için <code>npx github:caglarutkuguler/cubicle</code> çalıştırıp <code>http://127.0.0.1:3200</code> adresini açın.",
+    },
+  };
+  const params = new URLSearchParams(location.search);
+  const lang = (params.get('lang') || navigator.language || 'en').slice(0, 2).toLowerCase() === 'tr' ? 'tr' : 'en';
+  const L = STR[lang];
+  document.documentElement.lang = lang;
+  // Becomes true in init() as well when the page is served without the Cubicle
+  // proxy behind it (e.g. the hosted demo on GitHub Pages).
+  let DEMO = params.has('demo');
+
+  // ---------- setup ----------
+  const T = 16, CW = 352, CH = 208;
+  const cv = document.getElementById('c');
+  const g = cv.getContext('2d');
+  g.imageSmoothingEnabled = false;
+  const labelsEl = document.getElementById('labels');
+  const cardsEl = document.getElementById('cards');
+  const statusEl = document.getElementById('status');
+  const companySel = document.getElementById('company');
+  document.getElementById('hint').textContent = L.hint;
+  statusEl.textContent = L.connecting;
+
+  // Office layout, in tiles
+  const DESKS = [[1,3],[4.5,3],[8,3],[11.5,3],[1,7.5],[4.5,7.5],[8,7.5],[11.5,7.5],[1,10.5],[4.5,10.5],[8,10.5],[11.5,10.5]];
+  const LOUNGE = [[16,4.4],[18,4.4],[20,4.4],[16.2,10],[18.3,10.6],[20.3,10],[15.8,7.4],[21,7.4],[17,12],[19.5,12],[16.4,5.6],[19.6,5.6]];
+  const SHIRTS = ['#e05d5d','#4f9dde','#57b86b','#e0a33b','#a66de0','#3bc4c4','#e07ab8','#9aa0b4','#f07b3f','#6fcf97','#c9b458','#5f7ee0'];
+  const HAIRS  = ['#2b1d14','#111111','#6b3e1f','#c9a04a','#8b4513','#3b2a20','#d9d0c1','#4a2b1a'];
+  const SKINS  = ['#f1c7a3','#d9a47a','#b87b52','#f5d5b8','#c68e62'];
+
+  let paperclipUrl = '';
+  let companies = [];
+  let company = null;
+  const sprites = new Map();
+
+  const hash = (s) => { let h = 0; for (const ch of s) h = (h * 31 + ch.charCodeAt(0)) >>> 0; return h; };
+  const esc = (s) => String(s ?? '').replace(/[&<>"]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
+
+  // ---------- data sources ----------
+  async function getJSON(u) { const r = await fetch(u, { cache: 'no-store' }); if (!r.ok) throw new Error(r.status); return r.json(); }
+
+  const live = {
+    async companies() { return getJSON('/api/companies'); },
+    async agents(id) { return getJSON(`/api/companies/${id}/agents`); },
+    async issues(id) { return getJSON(`/api/companies/${id}/issues`); },
+  };
+
+  // Generic feed (docs/FEED.md): { company?, agents: [{ id, name, role?, status, task?, error? }] } or a bare array.
+  const STATUS_ALIASES = {
+    running: 'running', working: 'running', busy: 'running', active: 'running',
+    idle: 'idle', done: 'idle', finished: 'idle', ready: 'idle',
+    error: 'error', failed: 'error', crashed: 'error',
+    paused: 'paused', sleeping: 'paused', stopped: 'paused', offline: 'paused',
+    waiting: 'waiting', blocked: 'waiting', needs_input: 'waiting', permission: 'waiting',
+  };
+  const feed = {
+    label: '',
+    async companies() { return [{ id: 'feed', name: feed.label, issuePrefix: '' }]; },
+    async agents() {
+      const raw = await getJSON('/api/feed');
+      const list = Array.isArray(raw) ? raw : Array.isArray(raw?.agents) ? raw.agents : [];
+      if (raw && raw.company) document.getElementById('co').textContent = raw.company;
+      return list.map((a, i) => {
+        const t = a.task;
+        const task = !t ? null : typeof t === 'string'
+          ? { identifier: '', title: t, url: a.taskUrl || '' }
+          : { identifier: String(t.id ?? t.identifier ?? ''), title: t.title ?? '', url: t.url || '' };
+        return {
+          id: String(a.id ?? a.name ?? i), name: String(a.name ?? a.id ?? `agent ${i + 1}`),
+          title: a.role || a.title || '', createdAt: String(a.since ?? a.createdAt ?? i).padStart(20, '0'),
+          status: STATUS_ALIASES[String(a.status || 'idle').toLowerCase()] || 'idle',
+          errorReason: a.error || null, task,
+        };
+      });
+    },
+    async issues() { return []; },
+  };
+
+  const demo = (() => {
+    const t0 = Date.now();
+    const roster = [
+      ['CEO', 'Chief Executive'], ['WebDev', 'Web Developer'], ['SEO', 'SEO & Content'],
+      ['Growth', 'Growth Marketer'], ['Analyst', 'Functional Analyst'], ['QA', 'QA & Refactoring'],
+    ];
+    const tasks = ['Audit site health', 'Keyword research', 'Qualified leads shortlist', 'Review checkout flow', 'Refactor module', 'Write test checklist'];
+    const agents = roster.map(([name, title], i) => ({
+      id: `demo-${i}`, name, title, createdAt: `2026-01-01T00:0${i}:00Z`, status: 'idle', errorReason: null,
+    }));
+    function tick() {
+      const s = Math.floor((Date.now() - t0) / 1000);
+      agents.forEach((a, i) => {
+        const phase = Math.floor((s + i * 7) / (9 + i * 2)) % 5;
+        a.status = phase === 4 && i === 2 ? 'error' : phase === 3 && i === 3 ? 'waiting' : phase % 2 === 0 ? 'running' : 'idle';
+        a.errorReason = a.status === 'error' ? 'Example error: connection lost' : null;
+      });
+    }
+    return {
+      async companies() { return [{ id: 'demo', name: 'Demo Co.', issuePrefix: 'DEMO' }]; },
+      async agents() { tick(); return agents.map((a) => ({ ...a })); },
+      async issues() {
+        return agents.map((a, i) => ({ identifier: `DEMO-${i + 1}`, title: tasks[i], status: 'in_progress', assigneeAgentId: a.id }));
+      },
+    };
+  })();
+
+  let src = live;
+
+  async function init() {
+    const b = document.getElementById('banner');
+    if (!DEMO) {
+      try {
+        const cfg = await getJSON('/config.json');
+        if (cfg.source === 'feed') { src = feed; feed.label = cfg.label || 'feed'; }
+        else paperclipUrl = cfg.paperclipUrl || '';
+        // Reload when the server was updated or restarted.
+        if (cfg.build) setInterval(async () => {
+          try { if ((await getJSON('/config.json')).build !== cfg.build) location.reload(); } catch (_) {}
+        }, 60000);
+      } catch (_) {
+        // No Cubicle server behind this page: show the demo instead of an error.
+        DEMO = true;
+        b.innerHTML = L.hosted; b.style.display = 'block';
+      }
+    } else {
+      b.innerHTML = L.demo; b.style.display = 'block';
+    }
+    if (DEMO) src = demo;
+    poll();
+    setInterval(poll, 4000);
+    requestAnimationFrame(frame);
+  }
+
+  async function poll() {
+    try {
+      if (!company) {
+        companies = await src.companies();
+        if (!companies.length) { statusEl.textContent = L.noCompany; return; }
+        const want = params.get('company');
+        company = companies.find((c) => c.issuePrefix === want || c.id === want) || companies[0];
+        if (companies.length > 1) {
+          companySel.hidden = false;
+          companySel.innerHTML = companies.map((c) => `<option value="${esc(c.id)}">${esc(c.name)}</option>`).join('');
+          companySel.value = company.id;
+        }
+        document.getElementById('co').textContent = company.name;
+      }
+      const [agents, issues] = await Promise.all([src.agents(company.id), src.issues(company.id)]);
+      sync(agents, issues);
+      if (src === feed) {
+        const b = document.getElementById('banner');
+        if (!agents.length) { b.innerHTML = feed.label === 'Claude Code' ? L.emptyClaude : L.empty; b.style.display = 'block'; }
+        else b.style.display = 'none';
+      }
+      const running = agents.filter((a) => a.status === 'running').length;
+      statusEl.textContent = `${L.summary(agents.length, running)} · ${new Date().toLocaleTimeString(lang)}`;
+    } catch (e) {
+      const code = Number(e && e.message);
+      statusEl.textContent = src === feed ? L.feedUnreachable
+        : (code === 401 || code === 403) ? L.denied(code) : L.unreachable;
+    }
+  }
+
+  companySel.addEventListener('change', () => {
+    company = companies.find((c) => c.id === companySel.value);
+    document.getElementById('co').textContent = company.name;
+    for (const s of sprites.values()) s.el.remove();
+    sprites.clear();
+    const u = new URL(location.href); u.searchParams.set('company', company.issuePrefix); history.replaceState(null, '', u);
+    poll();
+  });
+
+  function currentTask(agentId, issues) {
+    const mine = issues.filter((i) => i.assigneeAgentId === agentId);
+    for (const st of ['in_progress', 'in_review', 'blocked', 'todo', 'backlog']) {
+      const f = mine.find((i) => i.status === st);
+      if (f) return f;
+    }
+    return null;
+  }
+
+  function sync(agents, issues) {
+    const sorted = [...agents].sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+    const seen = new Set();
+    sorted.forEach((a, idx) => {
+      seen.add(a.id);
+      let s = sprites.get(a.id);
+      if (!s) {
+        const h = hash(a.id);
+        const spot = LOUNGE[idx % LOUNGE.length];
+        s = {
+          id: a.id, idx, seed: (h % 1000) / 100,
+          shirt: SHIRTS[idx % SHIRTS.length], hair: HAIRS[h % HAIRS.length], skin: SKINS[(h >> 3) % SKINS.length],
+          x: spot[0] * T, y: spot[1] * T,
+          lounge: idx % LOUNGE.length, nextWander: performance.now() / 1000 + 5 + (h % 10),
+          bubble: null, bubbleClass: '', bubbleUntil: 0, prevStatus: a.status,
+        };
+        const el = document.createElement('div');
+        el.className = 'lbl';
+        el.innerHTML = '<div class="bub" style="display:none"></div><div class="name"></div>';
+        labelsEl.appendChild(el);
+        s.el = el;
+        sprites.set(a.id, s);
+      }
+      s.idx = idx;
+      s.desk = DESKS[idx % DESKS.length];
+      s.name = a.name;
+      s.role = a.title || a.role || '';
+      s.status = a.status;
+      s.error = a.errorReason || '';
+      s.task = a.task !== undefined ? a.task : currentTask(a.id, issues);
+      if (s.prevStatus === 'running' && s.status === 'idle') setBubble(s, L.done, 'ok', 6);
+      s.prevStatus = s.status;
+      s.el.querySelector('.name').textContent = s.name;
+    });
+    for (const [id, s] of sprites) if (!seen.has(id)) { s.el.remove(); sprites.delete(id); }
+    renderCards();
+  }
+
+  function setBubble(s, text, cls = '', secs = 4) {
+    s.bubble = text; s.bubbleClass = cls; s.bubbleUntil = performance.now() / 1000 + secs;
+  }
+
+  function taskLink(t) {
+    const label = esc(t.identifier);
+    if (t.url) return `<a href="${esc(t.url)}" target="_blank" rel="noopener">${label || '↗'}</a>`;
+    if (!paperclipUrl || DEMO) return label;
+    return `<a href="${esc(paperclipUrl)}/${esc(company.issuePrefix)}/issues/${esc(t.identifier)}" target="_blank" rel="noopener">${label}</a>`;
+  }
+
+  function renderCards() {
+    const list = [...sprites.values()].sort((a, b) => a.idx - b.idx);
+    cardsEl.innerHTML = list.map((s) => {
+      const t = s.task;
+      const taskHtml = t ? `${taskLink(t)} ${esc(t.title)}` : `<span style="color:var(--muted)">${L.noTask}</span>`;
+      const err = s.status === 'error' && s.error ? `<div class="st" style="color:#ffb3b8">${esc(s.error)}</div>` : '';
+      return `<div class="card"><div class="top"><span class="sw" style="background:${s.shirt}"></span><b>${esc(s.name)}</b></div>
+        <div class="role">${esc(s.role)}</div>
+        <div class="st"><span class="pill p-${esc(s.status)}">${esc(L[s.status] || s.status)}</span>${taskHtml}</div>${err}</div>`;
+    }).join('');
+  }
+
+  // ---------- movement ----------
+  function targetFor(s, now) {
+    if (s.status === 'running' || s.status === 'error' || s.status === 'waiting') return [s.desk[0] * T + 22, s.desk[1] * T + 12, true];
+    if (now > s.nextWander) {
+      const used = new Set([...sprites.values()].filter((o) => o !== s).map((o) => o.lounge));
+      const free = LOUNGE.map((_, i) => i).filter((i) => !used.has(i));
+      if (free.length) s.lounge = free[Math.floor(Math.random() * free.length)];
+      s.nextWander = now + 9 + Math.random() * 14;
+      if (Math.random() < 0.35) setBubble(s, L.chatter[Math.floor(Math.random() * L.chatter.length)], '', 3);
+    }
+    const p = LOUNGE[s.lounge];
+    return [p[0] * T, p[1] * T, false];
+  }
+
+  function step(s, dt, now) {
+    const [tx, ty, atDesk] = targetFor(s, now);
+    // Walk through the doorway between the work area and the lounge
+    const inWork = s.x < 14 * T, toWork = tx < 14 * T;
+    let gx = tx, gy = ty;
+    if (inWork !== toWork) {
+      const doorX = 14 * T + 8, doorY = 7 * T;
+      if (Math.abs(s.x - doorX) > 3 || Math.abs(s.y - doorY) > 3) { gx = doorX; gy = doorY; }
+      else { s.x += inWork ? 6 : -6; }
+    }
+    const dx = gx - s.x, dy = gy - s.y, d = Math.hypot(dx, dy);
+    if (d > 0.8) {
+      const m = Math.min(d, 34 * dt);
+      s.x += (dx / d) * m; s.y += (dy / d) * m;
+      s.walking = true; s.dir = Math.abs(dx) > Math.abs(dy) ? Math.sign(dx) : 0;
+    } else {
+      s.walking = false;
+    }
+    s.seated = !s.walking && atDesk && Math.hypot(tx - s.x, ty - s.y) < 1.5;
+    s.typing = s.seated && s.status === 'running';
+  }
+
+  // ---------- drawing ----------
+  const rect = (c, x, y, w, h) => { g.fillStyle = c; g.fillRect(Math.round(x), Math.round(y), w, h); };
+
+  function drawRoom(t) {
+    const hr = new Date().getHours();
+    const night = hr < 7 || hr >= 20;
+    for (let y = 2; y < 13; y++) for (let x = 0; x < 22; x++) {
+      const lounge = x >= 15;
+      rect((x + y) % 2 ? (lounge ? '#4a3d57' : '#3a3f56') : (lounge ? '#463a52' : '#363b51'), x * T, y * T, T, T);
+    }
+    rect('#5b4a6b', 16.5 * T, 6.3 * T, 4.6 * T, 3 * T);
+    rect('#4b4f6b', 0, 0, CW, 2 * T);
+    rect('#3a3d55', 0, 2 * T - 3, CW, 3);
+    for (const wx of [1.5, 5.5, 9.5, 16.5]) {
+      rect('#2c2f44', wx * T - 1, 5, 34, 18);
+      rect(night ? '#1c2a4a' : '#8fc7ff', wx * T, 6, 32, 16);
+      if (!night) { const cx = (t * 3 + wx * 11) % 44 - 8; rect('rgba(255,255,255,.85)', wx * T + cx, 11, 8, 3); rect('rgba(255,255,255,.85)', wx * T + cx + 2, 9, 4, 2); }
+      else rect('#f5f1c8', wx * T + 24, 9, 3, 3);
+      rect('#2c2f44', wx * T + 15, 6, 2, 16);
+    }
+    // wall clock
+    rect('#e9e7f2', 13 * T, 7, 12, 12); rect('#4b4f6b', 13 * T + 1, 8, 10, 10);
+    const now = new Date();
+    const hand = (a, len) => { g.beginPath(); g.moveTo(13 * T + 6, 13); g.lineTo(13 * T + 6 + Math.sin(a) * len, 13 - Math.cos(a) * len); g.stroke(); };
+    g.strokeStyle = '#e9e7f2'; g.lineWidth = 1;
+    hand(((now.getHours() % 12) + now.getMinutes() / 60) / 12 * Math.PI * 2, 3);
+    hand(now.getMinutes() / 60 * Math.PI * 2, 4);
+    // glass partition with a doorway
+    rect('rgba(160,200,255,.18)', 14 * T + 6, 2 * T, 4, 4 * T);
+    rect('rgba(160,200,255,.18)', 14 * T + 6, 8 * T, 4, 5 * T);
+    rect('#6c7090', 14 * T + 6, 2 * T, 4, 2); rect('#6c7090', 14 * T + 6, 8 * T, 4, 2);
+  }
+
+  function loungeProps(t, list) {
+    list.push({ z: 3.6 * T, f: () => {
+      rect('#6a3f8f', 15.8 * T, 2.4 * T, 5 * T, 12); rect('#7d4fa6', 15.8 * T, 2.4 * T + 12, 5 * T, 8);
+      for (let i = 0; i < 4; i++) rect('#9467bd', 16 * T + i * 19, 2.4 * T + 13, 16, 5);
+    }});
+    list.push({ z: 3.4 * T, f: () => {
+      rect('#3b3e4d', 21.1 * T, 2.2 * T, 12, 20); rect('#23252f', 21.1 * T + 2, 2.2 * T + 8, 8, 6);
+      rect(Math.floor(t * 2) % 2 ? '#ff5a5a' : '#8a2a2a', 21.1 * T + 9, 2.2 * T + 3, 2, 2);
+    }});
+    list.push({ z: 6.9 * T, f: () => {
+      rect('#8b5a2b', 17 * T, 6.9 * T, 3.6 * T, 1.6 * T); rect('#6e4520', 17 * T, 8.5 * T, 3.6 * T, 3);
+      rect('#e9e7f2', 17.4 * T, 7.2 * T, 10, 7); rect('#e9e7f2', 19.4 * T, 7.4 * T, 8, 6);
+    }});
+    for (const [px, py] of [[14.9, 2.3], [21.3, 11.6], [0.2, 12.1]]) list.push({ z: (py + 1) * T, f: () => {
+      rect('#8b5a2b', px * T + 3, py * T + 10, 8, 6);
+      rect('#3f9d55', px * T + 1, py * T, 12, 11); rect('#57b86b', px * T + 3, py * T - 3, 8, 6);
+    }});
+  }
+
+  function drawDesk(d, s, t) {
+    const x = d[0] * T, y = d[1] * T;
+    const on = s && s.typing;
+    const err = s && s.status === 'error' && s.seated;
+    const wait = s && s.status === 'waiting' && s.seated;
+    rect('#8b5a2b', x, y + 8, 34, 10); rect('#6e4520', x, y + 18, 34, 3);
+    rect('#6e4520', x + 1, y + 21, 2, 6); rect('#6e4520', x + 31, y + 21, 2, 6);
+    rect('#22252f', x + 3, y - 2, 14, 10);
+    rect(err ? (Math.floor(t * 2) % 2 ? '#ff6b6b' : '#a33') : wait ? (Math.floor(t) % 2 ? '#e0a33b' : '#b07d20') : on ? '#5cc8f0' : '#3a4050', x + 4, y - 1, 12, 7);
+    if (on) for (let i = 0; i < 3; i++) rect('rgba(255,255,255,.75)', x + 5, y + i * 2, (Math.floor(t * 9 + i * 4) % 9) + 1, 1);
+    rect('#22252f', x + 9, y + 8, 2, 1);
+    rect('#c9cbd6', x + 17, y + 10, 11, 2);
+    if (on) rect('#ffffff', x + 17 + (Math.floor(t * 12) % 10), y + 10, 1, 1);
+    rect('#f3f3f3', x + 29, y + 9, 3, 4); rect('#f3f3f3', x + 32, y + 10, 1, 2);
+  }
+
+  function drawChar(s, t) {
+    const x = Math.round(s.x), y = Math.round(s.y);
+    const bob = s.walking ? Math.floor(t * 8 + s.seed) % 2 : 0;
+    rect('rgba(0,0,0,.25)', x - 4, y - 1, 8, 2);
+    if (!s.seated) {
+      const ph = s.walking ? Math.floor(t * 8 + s.seed) % 2 : 0;
+      rect('#2b2f45', x - 3, y - 5, 2, ph ? 4 : 5);
+      rect('#2b2f45', x + 1, y - 5, 2, ph ? 5 : 4);
+    }
+    rect(s.shirt, x - 4, y - 11 - bob, 8, 6);
+    if (s.typing) {
+      const a = Math.floor(t * 10 + s.seed) % 2;
+      rect(s.skin, x - 5, y - 8 - bob - a, 2, 2);
+      rect(s.skin, x + 3, y - 8 - bob - (1 - a), 2, 2);
+    } else if (s.status === 'waiting' && s.seated) {
+      // one hand up, waving
+      const w = Math.floor(t * 3 + s.seed) % 2;
+      rect(s.skin, x - 5, y - 10 - bob, 1, 4);
+      rect(s.skin, x + 4 + w, y - 19 - bob, 2, 8);
+    } else {
+      rect(s.skin, x - 5, y - 10 - bob, 1, 4);
+      rect(s.skin, x + 4, y - 10 - bob, 1, 4);
+    }
+    const slump = s.status === 'error' && s.seated ? 1 : 0;
+    rect(s.skin, x - 3, y - 17 - bob + slump, 6, 6);
+    rect(s.hair, x - 3, y - 18 - bob + slump, 6, 2);
+    rect(s.hair, x - 3, y - 17 - bob + slump, 1, 2);
+    rect(s.hair, x + 2, y - 17 - bob + slump, 1, 2);
+    if (((t + s.seed) % 4) >= 0.14) {
+      const ox = s.dir || 0;
+      rect('#1a1a1a', x - 2 + ox, y - 14 - bob + slump, 1, 1);
+      rect('#1a1a1a', x + 1 + ox, y - 14 - bob + slump, 1, 1);
+    }
+  }
+
+  function placeLabels(now) {
+    const k = cv.clientWidth / CW;
+    for (const s of sprites.values()) {
+      s.el.style.left = (s.x * k) + 'px';
+      s.el.style.top = ((s.y - 20) * k) + 'px';
+      const b = s.el.querySelector('.bub');
+      let text = null, cls = '';
+      if (s.bubble && now < s.bubbleUntil) { text = s.bubble; cls = s.bubbleClass; }
+      else if (s.status === 'error' && s.seated) { text = L.errBubble; cls = 'err'; }
+      else if (s.status === 'waiting' && s.seated) { text = L.waitBubble; cls = 'wait'; }
+      else if (s.typing && s.task) text = '⌨ ' + (s.task.identifier || s.task.title);
+      else if (s.status === 'paused') text = 'zZ';
+      if (text) { b.textContent = text; b.className = 'bub ' + cls; b.style.display = ''; }
+      else b.style.display = 'none';
+    }
+  }
+
+  let last = performance.now() / 1000;
+  function frame() {
+    const now = performance.now() / 1000;
+    const dt = Math.min(0.1, now - last); last = now;
+    g.clearRect(0, 0, CW, CH);
+    drawRoom(now);
+    const list = [];
+    loungeProps(now, list);
+    const byDesk = new Map();
+    for (const s of sprites.values()) { step(s, dt, now); byDesk.set(s.desk, s); }
+    const deskCount = Math.max(4, Math.min(DESKS.length, Math.ceil(sprites.size / 4) * 4));
+    DESKS.slice(0, deskCount).forEach((d) => list.push({ z: d[1] * T + 21, f: () => drawDesk(d, byDesk.get(d), now) }));
+    for (const s of sprites.values()) list.push({ z: s.y, f: () => drawChar(s, now) });
+    list.sort((a, b) => a.z - b.z).forEach((o) => o.f());
+    placeLabels(now);
+    requestAnimationFrame(frame);
+  }
+
+  init();
+})();
+</script>
+</body>
+</html>