@caglarutkuguler/cubicle 0.3.0 → 0.4.0

package/README.md

@@ -4,6 +4,8 @@
 
 **[▶ Live demo](https://caglarutkuguler.github.io/cubicle/?lang=en)** — no install, fake agents.
 
+[![npm](https://img.shields.io/npm/v/@caglarutkuguler/cubicle)](https://www.npmjs.com/package/@caglarutkuguler/cubicle) [![CI](https://github.com/caglarutkuguler/cubicle/actions/workflows/ci.yml/badge.svg)](https://github.com/caglarutkuguler/cubicle/actions/workflows/ci.yml) ![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen) [![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
 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)
@@ -21,21 +23,21 @@ Requires Node.js 18+.
 **Paperclip** (default; expects Paperclip at `http://127.0.0.1:3100`):
 
 ```bash
-npx github:caglarutkuguler/cubicle
+npx @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
+npx @caglarutkuguler/cubicle install-hooks      # once; backs up ~/.claude/settings.json first
+npx @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
+npx @caglarutkuguler/cubicle --source ./agents.json
+npx @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).
@@ -63,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" |
@@ -83,9 +86,9 @@ Each card below the office links to the agent's current task when the source pro
 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
+PAPERCLIP_URL=https://paperclip.example.com PAPERCLIP_TOKEN=pcp_… npx @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
+npx @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`).
@@ -94,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.
@@ -129,7 +147,16 @@ 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
+
+Versions are published to npm by [`.github/workflows/release.yml`](.github/workflows/release.yml) with npm trusted publishing, so no npm token exists anywhere and every version carries a provenance attestation.
+
+```bash
+npm version patch            # or minor / major: bumps package.json, commits, tags vX.Y.Z
+git push --follow-tags       # CI tests, publishes to npm, creates the GitHub release
+```
 
 ## Credits
 
@@ -147,4 +174,4 @@ Cubicle is a community project and is not affiliated with or endorsed by Papercl
 
 **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.
+Kurulum: `npx @caglarutkuguler/cubicle` (Paperclip) veya `npx @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.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.0",
+  "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 = ''; }