@caglarutkuguler/cubicle 0.3.1 → 0.4.0

package/README.md

@@ -65,13 +65,14 @@ 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.
+- `?kiosk` fills the screen with the office for a TV or a second monitor: cards and footer hidden, names and bubbles scale with the screen, cursor hidden. Combined with the auto-updater, a wall display picks up new versions by itself.
 
 ## 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 |
+| `waiting` | Sits at its desk with a hand up, amber screen — it needs your input or approval. With Paperclip this comes from issues whose review is waiting on the board (for example pending ask-user questions); a busy agent keeps typing but its bubble flashes the issue id, and the header counts how many need you |
 | `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" |
@@ -96,6 +97,21 @@ Use a board API key with the narrowest read-only scope Paperclip lets you create
 
 **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).
 
+## How it compares
+
+Cubicle is one of several pixel offices for AI agents, all inspired by [Pixel Agents](https://github.com/pixel-agents-hq/pixel-agents). They optimise for different things:
+
+| | Cubicle | [Pixel Agents](https://github.com/pixel-agents-hq/pixel-agents) | [Agent Pixels](https://github.com/gcampton/Agent-Pixels) | [agents-in-the-office](https://github.com/gukosowa/agents-in-the-office) |
+| --- | --- | --- | --- | --- |
+| Works with | Paperclip, Claude Code, any JSON feed | Claude Code | Paperclip | Claude Code, Gemini CLI |
+| Runs as | Standalone page (`npx`, systemd, kiosk) | VS Code extension or `npx` browser app | Paperclip plugin | Standalone app |
+| Setup | One command, nothing to build | Marketplace install; build from source to hack on it | Build against the Paperclip plugin SDK | See its README |
+| Access to your agents | Read-only by design (GET allowlist) | Watches local Claude Code sessions | Inside Paperclip | Watches local sessions |
+| Shows "needs you" | Yes: permission prompts, board questions | Yes: waiting for approval | Not listed | Yes: approval alerts |
+| Office editor, art | Fixed room, programmer art | Layout editor, furniture and character assets, pets | 80+ characters, multi-room views | Tile map editor, sound packs |
+
+**Pick Cubicle** if you want something you can trust to run next to production agents (it can only read), that starts in seconds with no build, or that shows Paperclip and Claude Code in one place. **Pick another one** if you want to design your office, richer art, or tighter editor integration.
+
 ## 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.
@@ -131,7 +147,7 @@ journalctl --user -u cubicle-update.service   # what it did
 
 ## 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).
+Issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) for the few ground rules (zero dependencies, read-only). Look for issues labelled [good first issue](https://github.com/caglarutkuguler/cubicle/labels/good%20first%20issue). 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).
 
 ## Releasing
 

package/bin/cubicle.js

@@ -32,6 +32,11 @@ if (process.argv[2] === 'install-hooks') {
   return;
 }
 
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+  console.log(require('../package.json').version);
+  process.exit(0);
+}
+
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(`Cubicle — a live pixel-art office for your AI agents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caglarutkuguler/cubicle",
-  "version": "0.3.1",
+  "version": "0.4.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"

package/public/index.html

@@ -17,13 +17,21 @@
   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; }
+  #labels { position:absolute; inset:0; pointer-events:none; font-size:11px; }
   .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 { background:#fff; color:#1d1f2b; border-radius:.82em; padding:.18em .64em; font-size:1em; font-weight:600; margin-bottom:.27em; 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; }
+  .name { background:rgba(15,16,26,.78); color:#fff; font-size:1em; font-weight:600; padding:.09em .55em; border-radius:.45em; }
+  /* ?kiosk: the office fills the screen, for a TV or a second monitor */
+  body.kiosk { overflow:hidden; cursor:none; }
+  body.kiosk .wrap { max-width:none; padding:0; height:100vh; display:flex; align-items:center; justify-content:center; }
+  body.kiosk header { position:fixed; top:0; left:0; right:0; z-index:2; margin:0; padding:1vh 1.4vw; background:linear-gradient(rgba(10,11,18,.8), rgba(10,11,18,0)); }
+  body.kiosk h1 { font-size:clamp(16px, 1.5vw, 34px); }
+  body.kiosk h1 small, body.kiosk #status { font-size:clamp(12px, 1.05vw, 24px); }
+  body.kiosk #stage { width:min(100vw, calc(100vh * 352 / 208)); border:0; border-radius:0; }
+  body.kiosk #cards, body.kiosk footer, body.kiosk #banner, body.kiosk #company { display:none !important; }
   #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; }
@@ -75,6 +83,7 @@
       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',
+      asks: 'waiting for your answer on', needYou: (n) => `${n} need${n === 1 ? 's' : ''} 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.',
@@ -87,6 +96,7 @@
       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',
+      asks: 'cevabınızı bekliyor:', needYou: (n) => `${n} 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.",
@@ -94,12 +104,16 @@
     },
   };
   const params = new URLSearchParams(location.search);
-  const lang = (params.get('lang') || navigator.language || 'en').slice(0, 2).toLowerCase() === 'tr' ? 'tr' : 'en';
+  // Any language with a block in STR is picked from ?lang=xx or the browser language; English otherwise.
+  const wantLang = (params.get('lang') || navigator.language || 'en').slice(0, 2).toLowerCase();
+  const lang = STR[wantLang] ? wantLang : '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');
+  const KIOSK = params.has('kiosk');
+  if (KIOSK) document.body.classList.add('kiosk');
 
   // ---------- setup ----------
   const T = 16, CW = 352, CH = 208;
@@ -244,7 +258,8 @@
         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)}`;
+      const needYou = [...sprites.values()].filter((x) => x.status === 'waiting' || x.ask).length;
+      statusEl.textContent = `${L.summary(agents.length, running)}${needYou ? ' · ' + L.needYou(needYou) : ''} · ${new Date().toLocaleTimeString(lang)}`;
     } catch (e) {
       const code = Number(e && e.message);
       statusEl.textContent = src === feed ? L.feedUnreachable
@@ -270,6 +285,18 @@
     return null;
   }
 
+  // Paperclip: an open issue whose review is waiting on the board (a pending question or
+  // interaction for a human) means the agent needs you, even though Paperclip reports it idle.
+  function askingBoard(agentId, issues) {
+    for (const i of issues) {
+      if (i.assigneeAgentId !== agentId || ['done', 'cancelled'].includes(i.status)) continue;
+      const paths = (i.reviewAttention && i.reviewAttention.paths) || [];
+      const p = paths.find((x) => /board|user|human/i.test(String(x && x.responder || '')));
+      if (p) return { issue: i, reason: String(p.label || '') };
+    }
+    return null;
+  }
+
   function sync(agents, issues) {
     const sorted = [...agents].sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
     const seen = new Set();
@@ -300,6 +327,9 @@
       s.status = a.status;
       s.error = a.errorReason || '';
       s.task = a.task !== undefined ? a.task : currentTask(a.id, issues);
+      s.waitReason = '';
+      s.ask = a.task === undefined && a.status !== 'error' ? askingBoard(a.id, issues) : null;
+      if (s.ask && a.status === 'idle') { s.status = 'waiting'; s.task = s.ask.issue; s.waitReason = s.ask.reason; }
       if (s.prevStatus === 'running' && s.status === 'idle') setBubble(s, L.done, 'ok', 6);
       s.prevStatus = s.status;
       s.el.querySelector('.name').textContent = s.name;
@@ -324,7 +354,9 @@
     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>` : '';
+      const err = s.status === 'error' && s.error ? `<div class="st" style="color:#ffb3b8">${esc(s.error)}</div>`
+        : s.status === 'waiting' && s.waitReason ? `<div class="st" style="color:#ffe08a">${esc(s.waitReason)}</div>`
+        : s.ask ? `<div class="st" style="color:#ffe08a">✋ ${L.asks} ${taskLink(s.ask.issue)} ${esc(s.ask.issue.title)}</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>`;
@@ -472,14 +504,20 @@
 
   function placeLabels(now) {
     const k = cv.clientWidth / CW;
+    // Keep bubbles narrower than the gap between neighbouring desks so they never overlap.
+    const bubMax = Math.max(80, Math.floor(3.3 * T * k - 6)) + 'px';
+    // In kiosk mode names and bubbles grow with the screen (11px at the default ~3x scale).
+    if (KIOSK) labelsEl.style.fontSize = Math.max(11, Math.round(11 * k / 3)) + 'px';
     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');
+      b.style.maxWidth = bubMax;
       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.ask && Math.floor(now / 3) % 2) { text = '✋ ' + (s.ask.issue.identifier || L.waiting); 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 = ''; }