piu-piu-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to piu-piu. Versions follow [semver](https://semver.org).
+
+## 0.1.0 (2026-10-05)
+
+First release.
+
+- **The office:** every Claude Code session on your machine is a person in a 3D isometric building with day, sunset and night lighting. People type while tools run, raise a hand when they need you, and take breaks in the lounge, at ping-pong or at baby-foot.
+- **Chat with any agent** through a live Claude Code process, with:
+  - permission approvals, Claude-Code-style question cards and plan approval;
+  - slash commands;
+  - modes (Ask first, Auto-edit, Plan, Allow all).
+- **The real Claude Code in the page:** a node-pty terminal with xterm.js. Expand it to full screen, collapse it while the agent works, or choose it as the default view in settings.
+- **Resume conversations** under the same names as Claude Code's `/resume`, or open Claude Code's own resume picker in the terminal.
+- **Specialists:** your Claude Code agents (user, project, plugin, built-in) have desks, work when called, link to their caller, and bring in colleagues for parallel calls. Each call opens read-only in the sidebar.
+- **Skills** show as a badge on the session using them.
+- **Channel:** talk to an open terminal session from the office, and approve its permission prompts there.
+- **The `piu-piu` command:** `setup`, `status`, `start`/`stop`/`restart` (refuses while agents work), `run`, `logs`, `doctor`, `uninstall`.
+- **Background service** (launchd or systemd user unit). Your data lives in `~/.piu-piu`.

package/README.md

@@ -0,0 +1,406 @@
+<p align="center">
+  <img src="https://unpkg.com/piu-piu-cli@0.1.0/docs/banner.svg" alt="piu-piu: a 3D office for your Claude Code agents" width="100%">
+</p>
+
+<p align="center">
+  <img alt="Claude Code" src="https://img.shields.io/badge/Claude_Code-D97757?style=for-the-badge&logo=claude&logoColor=white">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white">
+  <img alt="React" src="https://img.shields.io/badge/React_19-20232A?style=for-the-badge&logo=react&logoColor=61DAFB">
+  <img alt="Three.js" src="https://img.shields.io/badge/Three.js-000000?style=for-the-badge&logo=threedotjs&logoColor=white">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js_24+-5FA04E?style=for-the-badge&logo=nodedotjs&logoColor=white">
+  <img alt="Fastify" src="https://img.shields.io/badge/Fastify-000000?style=for-the-badge&logo=fastify&logoColor=white">
+  <img alt="SQLite" src="https://img.shields.io/badge/SQLite-003B57?style=for-the-badge&logo=sqlite&logoColor=white">
+  <img alt="Vite" src="https://img.shields.io/badge/Vite-646CFF?style=for-the-badge&logo=vite&logoColor=white">
+  <img alt="pnpm" src="https://img.shields.io/badge/pnpm-F69220?style=for-the-badge&logo=pnpm&logoColor=white">
+  <img alt="macOS" src="https://img.shields.io/badge/macOS-000000?style=for-the-badge&logo=apple&logoColor=white">
+</p>
+
+# piu-piu
+
+piu-piu shows every Claude Code session on your machine as a person in a 3D isometric office.
+
+- **People:** each session sits at a desk and types while it works. It raises a hand when it needs you, and takes a break in the lounge when it's idle.
+- **Specialists:** your Claude Code agents (`~/.claude/agents`, plugins, built-ins) are people with their own desks. They get to work whenever a session calls them.
+- **Control:** you talk to any agent from the office. From there you can approve or deny its tool calls, answer its questions, run slash commands and switch modes. You can also resume old conversations, or open the **real Claude Code** in a terminal inside the page.
+
+It runs locally. One daemon on `127.0.0.1:7777` watches `~/.claude` and serves the office web app. Nothing leaves your machine.
+
+```bash
+npm i -g piu-piu
+piu-piu setup
+```
+
+---
+
+## Contents
+
+- [What it does](#what-it-does)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Commands](#commands)
+- [Connect your terminal sessions](#connect-your-terminal-sessions)
+- [Using the office](#using-the-office)
+- [Agents, specialists and skills](#agents-specialists-and-skills)
+- [Configuration](#configuration)
+- [Running Claude in a VM, office on the host](#running-claude-in-a-vm-office-on-the-host)
+- [How it works](#how-it-works)
+- [HTTP and WebSocket API](#http-and-websocket-api)
+- [Security model](#security-model)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Releases](#releases)
+- [Uninstall](#uninstall)
+
+---
+
+## What it does
+
+### See
+| In the office | What it means |
+|---|---|
+| Typing at the desk | A tool is running (the label shows which one: `Bash: npm test`, `Edit: src/app.ts`) |
+| Hands on the keyboard, still | Thinking or generating |
+| Raised hand and amber light | Waiting for you: a permission prompt or a question |
+| Head in hands | The session hit an error |
+| Lounge, ping-pong, baby-foot | Idle for 5+ minutes. Games need at least 2 people on a break; anyone alone gets the sofa and a coffee |
+| Dashed coloured line between two people | A specialist (subagent) working for the session it's linked to |
+| `using devops-mz` badge | The session is running that skill this turn |
+
+### Talk and control
+- **Chat with any agent.** Office messages go to a live Claude Code process for that agent, in its folder, with its full conversation.
+- **Approvals and questions.** Permission prompts become Allow/Deny cards. `AskUserQuestion` questions become choice cards, like in Claude Code, and plan approval (`ExitPlanMode`) shows the plan.
+- **Modes**, from one dropdown: Ask first, Auto-edit, Plan, or Allow all (`--dangerously-skip-permissions`). A change applies straight away, even mid-task.
+- **Slash commands.** Type `/` for the agent's real command list, including your custom commands and skills.
+- **Full history.** A terminal session's own conversation is mirrored into the chat. Use "Show earlier messages" to page back through it.
+- **Real terminal.** Toggle any conversation to Terminal and you get the real `claude` CLI running in a pseudo-terminal, drawn with xterm.js: pickers, Shift+Tab, everything. You can expand it to full screen and collapse it while the agent keeps working.
+- **Resume, rename, create.**
+  - Start a new agent on any folder, or resume one of its earlier conversations. The names match Claude Code's `/resume`.
+  - Or open Claude Code's own resume picker in the terminal.
+- **Take over closed terminals.** Close a terminal session and your next office message continues the same conversation through the Agent SDK.
+
+---
+
+## Requirements
+
+- **macOS** (tested on macOS 26) or **Linux** (background service via systemd user units)
+- **Node.js 24+** (uses the built-in `node:sqlite`)
+- **Claude Code**, installed and logged in (`claude` on your PATH, or at `~/.local/bin/claude`)
+- Linux only: `build-essential`, `python3` (node-pty compiles there) and `lsof`
+
+---
+
+## Install
+
+```bash
+npm i -g piu-piu
+piu-piu setup
+```
+
+On **Linux**, node-pty compiles during install, and npm 11 blocks install scripts for global packages. Allow it:
+`npm i -g piu-piu-cli --allow-scripts=node-pty`
+
+`piu-piu setup` does the following, and is safe to run again after an upgrade:
+1. Installs the Claude Code hooks for real-time status, in `~/.claude/settings.json` (a backup is written first).
+2. Registers the channel, so the office can talk to open terminal sessions.
+3. Installs the background service, which starts at login and restarts if it stops: launchd on macOS, systemd `--user` on Linux.
+4. Opens **http://127.0.0.1:7777**.
+
+Your data lives in `~/.piu-piu`, so upgrades never touch it.
+
+**Upgrade:** `npm i -g piu-piu-cli@latest && piu-piu restart`
+
+**From source:**
+
+```bash
+git clone https://github.com/T4ruxx/piu-piu.git && cd piu-piu
+pnpm install && pnpm build
+pnpm piu-piu setup        # same CLI, running from the checkout
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `piu-piu setup` | Hooks, channel and background service, then opens the office |
+| `piu-piu open` | Opens the office in your browser |
+| `piu-piu status` | Sessions open, working and waiting; specialists at work; approvals; terminals |
+| `piu-piu start` · `stop` · `restart` | The background service. `stop` and `restart` refuse while an agent is working in the office; add `--force` to go ahead anyway |
+| `piu-piu run` | Runs in the foreground instead of as a service |
+| `piu-piu logs [-f]` | Shows or follows the log |
+| `piu-piu hooks install` · `uninstall` | Claude Code hooks only |
+| `piu-piu channel install` · `uninstall` | The channel only |
+| `piu-piu service install` · `uninstall` | Start at login only |
+| `piu-piu doctor` | Checks Node, Claude Code, terminal support, hooks, channel, service and port |
+| `piu-piu uninstall` | Removes the service, hooks and channel. Keeps `~/.piu-piu` |
+| `piu-piu --version` | Prints the installed version |
+
+---
+
+## Connect your terminal sessions
+
+piu-piu sees every session through its transcript files with no setup at all. Two optional additions make it real-time and two-way.
+
+### 1. Hooks: instant status
+
+Installed by `piu-piu setup`, or on their own with `piu-piu hooks install` (`piu-piu hooks uninstall` removes them).
+
+The hooks cover SessionStart, UserPromptSubmit, Pre/PostToolUse, Notification, Stop, SubagentStart, SubagentStop and SessionEnd.
+
+- Each one is a `curl` to the daemon with a 1-second timeout, so a stopped daemon never slows Claude Code down.
+- Without hooks, the office still works from transcripts. "Waiting for you" is the main signal that only hooks give in real time.
+
+### 2. Channel: talk to an open terminal session from the office
+
+Registered by `piu-piu setup` (or `piu-piu channel install`). Start the sessions you want to reach from the office with:
+
+```bash
+claude --dangerously-load-development-channels server:piu-piu
+```
+
+Messages you send from the office arrive in that terminal session, and Claude answers back into the office chat. Its permission prompts are relayed to the office too. Without the channel, an open terminal session is read-only in the office until you close it. After that, the office takes the conversation over.
+
+---
+
+## Using the office
+
+### Navigation
+| Action | How |
+|---|---|
+| Open someone's conversation | Click their figure, or pick them in **Team** |
+| Jump to any agent | `⌘K` / `Ctrl+K` |
+| Rotate / pan / zoom | Drag / right-drag / scroll |
+| Dock the sidebar beside the office | Dock button in the sidebar header |
+| Close the switcher, collapse full screen, close the sidebar | `Esc` (in that order) |
+| Lighting | Auto (follows your clock), day, sunset, night |
+
+### Sidebar
+- **Team:** everyone, grouped by team, with filters for Working, Waiting and On a break. Specialists are listed at the bottom.
+- **Inbox:** every approval and question waiting for you, across all agents.
+- **Activity:** a live feed of prompts, tools, turns, and specialists being called.
+- **Conversation:**
+  - The project bar shows the folder, git branch and path.
+  - The status strip shows the context window and session cost.
+  - The ⋯ menu has: rename, star, stop, new conversation, resume, close the terminal, remove agent, copy the session id.
+
+### Chat or terminal
+- Each conversation has a **Chat / Terminal** toggle.
+- **Settings (gear) → Conversations open in** sets the default.
+- When a terminal is closed, the Terminal view offers three choices:
+  - **Continue "&lt;title&gt;"** runs `claude --resume <session>`.
+  - **Pick a conversation to resume…** runs `claude --resume`, Claude Code's own picker.
+  - **New conversation** starts fresh.
+- While an agent's terminal is running, chat is paused for it, so two writers never share one session. The terminal keeps running when you switch away, and its output is replayed when you come back.
+
+### Creating agents
+- **Team → New agent:** choose a name, folder, role and room. You can start fresh or continue a past conversation in that folder, optionally with Allow all.
+- Renaming a "freelancer" (a session in a folder no agent owns) turns it into a named agent and keeps its chat.
+
+---
+
+## Agents, specialists and skills
+
+| Kind | What it is | How it shows |
+|---|---|---|
+| **Agent** | A folder you work in: from `agents.yaml`, created in the office, or a "freelancer" for any other folder with a session | A person at a desk. One figure per agent; a second figure only for a parallel busy terminal |
+| **Specialist** | A Claude Code agent definition: `~/.claude/agents/*.md`, `<project>/.claude/agents/*.md`, enabled plugin agents, and built-ins (Explore, Plan, general-purpose, claude-code-guide, statusline-setup, fork) | A person with a home desk, wearing the agent's `color`. Gets a desk once called in the last 30 days; the rest are listed "on call" |
+| **Skill** | `~/.claude/skills/<name>` or a project skill. It runs **inside** the calling session | A `using <skill>` badge on that session |
+
+**Specialists in practice**
+- **When a session calls one** (`Task` / `Agent` tool), the specialist works at their own desk. A dashed line in their colour runs to the caller, and their label reads `For Lamine · Read: src/app.ts`.
+- **Parallel calls** of the same agent bring in colleagues ("Explore · 2") at free desks.
+- **Each call opens read-only in the sidebar:** the caller's brief, the tools it used and the answer it handed back. A caller's chat shows a **Helping now** strip, and its `Agent:` tool rows link to the call.
+- **Home rooms** come from the agent's name and description:
+  - docs, wiki, explore, plan → library
+  - devops, infra, deploy, security → server room
+  - seo, content, design, film → Studio B
+  - anything else → dev floor
+- **Desks:** a full room spills over to the next one. Override the room in `agents.yaml` (see below).
+
+---
+
+## Configuration
+
+### `agents.yaml`
+
+```yaml
+agents:
+  - id: budget                 # stable id (chat history is keyed by it)
+    name: Léa                  # shown in the office
+    role: dev                  # dev | lead | devops | web | design | docs | qa | product
+    room: dev-floor            # dev-floor | server-room | library | studio-b
+    cwd: ~/workspace/budget    # sessions in this folder (and subfolders) sit at this desk
+    instructions: |            # optional, appended to Claude Code's system prompt for office chats
+      Prefer small PRs.
+    permissionMode: default    # optional starting mode: default | acceptEdits | plan
+
+# optional: seat specialists in a specific room
+specialists:
+  mazestudio-docs: library
+  devops-agent: server-room
+```
+
+- The **longest matching folder** wins, so a session in `~/workspace/budget/api` goes to `budget`.
+- This file lives at `~/.piu-piu/agents.yaml` and is created on first run. Agents created in the office live in `~/.piu-piu/agents.json`. They own their **exact** folder only, and can be removed from the office.
+
+### Environment
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PIU_PIU_HOST` | `127.0.0.1` | Address the daemon listens on |
+| `PIU_PIU_PORT` | `7777` | Port for the office, API, hooks and channel |
+| `PIU_PIU_HOME` | `~/.piu-piu` | Where your data lives |
+| `PIU_PIU_URL` | `ws://127.0.0.1:7777/channel` | Where the channel server connects (set in the MCP server's env) |
+
+Set these when running `piu-piu setup` or `piu-piu service install`, and the service keeps them.
+
+### Files
+
+| Path | Contents |
+|---|---|
+| `~/.piu-piu/agents.yaml` | Your roster (see above) |
+| `~/.piu-piu/office.db` | SQLite: sessions, events, office chats, agent modes, agent ↔ session links |
+| `~/.piu-piu/agents.json` | Agents created in the office |
+| `~/.piu-piu/channel-token` | Secret the channel must present (mode 600) |
+| `~/Library/Logs/piu-piu.log` (macOS) · `~/.piu-piu/piu-piu.log` (Linux) | Service log (`piu-piu logs`) |
+
+---
+
+## Running Claude in a VM, office on the host
+
+The daemon has to run **where Claude Code runs**: it reads `~/.claude`, receives hooks and starts `claude`. The browser is only a client. With VirtualBox NAT port forwarding:
+
+1. In the VM, run `PIU_PIU_HOST=0.0.0.0 piu-piu setup` (keep port 7777). NAT forwarding targets the VM's own address, not its loopback.
+2. Forward **host 127.0.0.1:7777 → guest 7777**. Binding the host side to 127.0.0.1 keeps it off your network.
+3. On the host, open `http://localhost:7777`. The port must stay 7777: the daemon only accepts pages served from `localhost`/`127.0.0.1` on its own port.
+4. On a Linux guest:
+   - `apt install lsof build-essential python3`. `lsof` is used to verify that hook and channel connections really come from your Claude processes.
+   - The service is a systemd user unit. On a server without a login session, run `loginctl enable-linger $USER` so it keeps running.
+
+---
+
+## How it works
+
+```
+ ~/.claude/projects/**.jsonl ──┐            ┌── office (React + three.js) ── you
+ ~/.claude/…/subagents/*.jsonl ┤            │     WebSocket /ws, /terminal/:id
+ Claude Code hooks (curl) ─────┼─► daemon ◄─┤
+ channel MCP server (per tty) ─┘  :7777     └── Agent SDK / node-pty ── claude
+                                  SQLite
+```
+
+- **apps/daemon** (Fastify, `node:sqlite`, chokidar)
+  - **Watching:** tails every transcript and the subagent transcripts, and receives hooks. It keeps one state per session and broadcasts every change over `/ws`.
+  - **Agent runtime:** runs one live Claude Code process per agent through `@anthropic-ai/claude-agent-sdk` (streaming input). It handles `canUseTool` approvals, modes and slash commands, and closes idle processes after 20 minutes.
+  - **Terminals:** starts the real `claude` in a node-pty pseudo-terminal per agent and keeps 2 MB of scrollback.
+  - **Specialists:** reads agent definitions and follows each run from `subagents/agent-*.meta.json` and `.jsonl`.
+- **apps/office** (Vite, React 19, @react-three/fiber, drei, zustand, xterm.js)
+  - The scene is a pure function of daemon state (`computeFigures`): desks, the lounge, games, specialists and links.
+  - People are procedural, with IK arms on keyboards, paddles and rods.
+- **apps/channel:** an MCP server using Claude Code's channels preview. It links one terminal session to the office in both directions and relays its permission prompts.
+- **packages/shared:** the types used on both sides of the wire.
+
+---
+
+## HTTP and WebSocket API
+
+Local only. Browser requests must come from the office's own origin (see [Security model](#security-model)).
+
+| Method & path | Purpose |
+|---|---|
+| `GET /api/state` | Snapshot: roster, sessions, events, approvals, running agents, terminals, specialists, recent subagent runs |
+| `GET /api/sessions/:id/transcript?before=<offset>` | A session's own conversation, paged by byte offset |
+| `GET /api/subagents/:id/transcript` | A specialist call's own conversation |
+| `GET /api/specialists/:type/runs` | Recent calls of one specialist |
+| `GET /api/agents/:id/chat` | Office chat history |
+| `POST /api/agents/:id/messages` `{text}` | Send a message (or `/command`) to an agent |
+| `POST /api/agents/:id/stop` · `/reset` | Stop the current task · start a new conversation |
+| `POST /api/agents/:id/mode` `{mode}` | `default` · `acceptEdits` · `plan` · `bypassPermissions` |
+| `GET /api/agents/:id/commands` | Slash commands and the current mode |
+| `POST /api/agents/:id/resume` `{sessionId}` | Continue an earlier conversation |
+| `POST /api/agents/:id/terminal` `{cols,rows,how}` | Open the real Claude Code. `how`: `continue` · `pick` · `new` |
+| `DELETE /api/agents/:id/terminal` | Close it |
+| `POST /api/agents` · `PATCH /api/agents/:id` · `DELETE /api/agents/:id` | Create (optionally adopting a freelancer) · rename · remove |
+| `GET /api/folders?q=` · `GET /api/folders/sessions?cwd=` | Folder suggestions · past conversations in a folder |
+| `POST /api/approvals/:id` `{behavior, answers?, message?}` | Answer a permission prompt or question |
+| `POST /hooks/:event` | Claude Code hooks |
+| `WS /ws` | Live state: `snapshot`, `session`, `event`, `chat`, `transcript`, `approval`, `running`, `roster`, `terminals`, `specialists`, `subagent` |
+| `WS /terminal/:id` | Terminal I/O: `{type:'input'\|'resize'}` in, `{type:'data'\|'exit'}` out |
+| `WS /channel` | Channel servers (token-authenticated) |
+
+---
+
+## Security model
+
+- **Network:** the daemon binds to `127.0.0.1` only.
+- **Origin check:** `/api`, `/ws`, `/terminal` and `/channel` reject browser requests from any origin other than the office itself. Without it, any website you visit could drive your agents through localhost.
+- **Hook links:** a hook's `X-Claude-Pid` link to a session is accepted only after checking, with `lsof`/`ps`, that the request really comes from a child of that Claude process.
+- **Channel:** a channel must present the secret in `data/channel-token` (readable only by your user) and pass the same ancestry check.
+- **Allow all** is opt-in per agent, starts Claude Code with `--dangerously-skip-permissions`, and is forgotten if an agent id is reused.
+- **Office terminals** run `claude` as your user, in the agent's folder: the same as typing it yourself.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| Anything | Start with `piu-piu doctor` |
+| Office is empty | `piu-piu status`. Sessions idle for 30+ minutes are hidden |
+| Nobody raises a hand on prompts | `piu-piu hooks install` |
+| "Forbidden origin" | Open the office at `http://127.0.0.1:7777` or `http://localhost:7777` (same port) |
+| Can't type to an open terminal session | Start it with `--dangerously-load-development-channels server:piu-piu`, or close it and continue from the office |
+| Terminal shows "Do you trust this folder?" | That's Claude Code's first-run prompt for that folder. Answer it once |
+| `posix_spawnp failed` when opening a terminal | Reinstall (`npm i -g piu-piu-cli`): the install step fixes node-pty's spawn-helper permissions |
+| A specialist stays "working" | Runs end on handback, on SubagentStop, or after 10 minutes without activity. Install hooks for instant updates |
+| Logs | `piu-piu logs -f` |
+
+---
+
+## Development
+
+```bash
+pnpm daemon          # daemon with reload (tsx watch) on :7777
+pnpm office          # Vite dev server on :5173, proxies /api, /ws and /terminal to the daemon
+pnpm typecheck       # all packages
+pnpm check           # scene checks: hands on keyboards, ping-pong rally, baby-foot rods, specialist desks
+pnpm build           # the npm package: office + bundled daemon + channel in packages/piu-piu/dist
+pnpm piu-piu <cmd>   # the CLI, from the checkout
+```
+
+```
+apps/daemon/src
+  observe/     transcripts.ts · hooks.ts · mirror.ts · subagents.ts · specialists.ts · skills.ts
+  runtime/     agents.ts (Agent SDK) · terminals.ts (node-pty) · peer.ts (process ancestry)
+  server.ts · state.ts · store.ts · roster.ts · folders.ts
+apps/office/src
+  layout.ts    who sits where (pure)
+  scene/       Building · Furniture · Decor · Person · poses (IK) · FigureView · HelpLink
+  ui/          Sidebar · Conversation · TerminalView · Specialists · AgentForms
+apps/channel/channel.mjs
+packages/shared/src/index.ts
+packages/piu-piu    the published package: bin/piu-piu.mjs (CLI), scripts/build.mjs
+```
+
+---
+
+## Releases
+
+Versions follow [semver](https://semver.org). Each release has a section in [CHANGELOG.md](CHANGELOG.md).
+
+1. On a branch, run `pnpm release patch` (or `minor` / `major`). This bumps `packages/piu-piu/package.json`, adds a CHANGELOG section listing the commits since the last release, and commits it.
+2. Open a pull request. CI typechecks, runs the scene checks and builds the package.
+3. Merge to `main`. The **Release** workflow publishes the new version to npm with trusted publishing (no npm token), tags it `vX.Y.Z` and creates a GitHub release.
+
+Merges that don't change the version publish nothing. Only `main` publishes.
+
+---
+
+## Uninstall
+
+```bash
+piu-piu uninstall        # service, hooks and channel
+npm rm -g piu-piu
+rm -rf ~/.piu-piu        # your data, if you want it gone too
+```