pi-kanban 0.3.1 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 2.0.0
+
+pi-kanban is now an agent development environment for pi. The board runs pi sessions in a browser terminal, next to their todos, subagents, and docs.
+
+### Breaking changes
+
+- The pi extension no longer starts the board. Install it with `npm install -g pi-kanban` and run `pi-kanban` in a shell.
+- `/kanban start`, `stop`, `restart`, `status`, and `open web|app` are gone. `/kanban` and `/kanban open` open the board with its access token.
+- The JSON themes are gone. The board has color themes in a palette menu, and `T` switches light and dark.
+- The board no longer opens files or folders in your editor. A file the preview cannot show gets a card with a Copy path button.
+
+### Features
+
+- **Board terminal.** Runs pi next to each session's board, on by default. `--no-terminal` turns it off. The terminal keeps running when the browser tab closes.
+- **New session dialog.** Pick a folder or project, and set the name, first prompt, model, and thinking level. `Ctrl+Alt+R` resumes an older session.
+- **Skills.** `kanban`, `show`, `ask`, `visualize`, and `dispatch` teach pi the `pi-kanban` command, so the board adds skill descriptions to the system prompt in place of tool schemas. pi adds panes, links and previews docs, posts `show` cards, and opens pi-cost or pi-inspect through the command.
+- **`ask` tool.** Shows an HTML question in a modal and waits for the answer. pi asks in its own prompt when the board is down.
+- **Dispatch.** `pi-kanban dispatch start` hands a task to a new pi session in the board terminal. The worker calls the `dispatch_report` tool, and the board keeps the report until the parent gets it with `pi-kanban dispatch wait`.
+- **Panes and preview.** Tabs next to the terminal hold files, URLs, pi-cost, and pi-inspect. The preview shows linked docs and scratchpad files in the board's colors.
+- **Board messages to pi.** Review comments, card answers, and task moves reach pi as user messages.
+- **Scratchpad.** A folder per session, given to pi in the system prompt and `$PI_SCRATCHPAD_DIR`, deleted 7 days after the session ends.
+- **Command line.** `pi-kanban doc|pane|show|session|group|task|project|dispatch|terminal|skills` talks to a running board.
+- Sessions get their title from the first prompt.
+
+### Security
+
+- The terminal and dispatch need a random token, which the board keeps in the URL fragment.
+- The board refuses requests with a non-local `Host` header and cross-site requests that change data.

package/README.md

@@ -2,50 +2,90 @@
 
 [![npm version](https://img.shields.io/npm/v/pi-kanban.svg)](https://www.npmjs.com/package/pi-kanban)
 
-Web dashboard for the [pi coding agent](https://pi.dev/packages/pi-kanban?name=kanban) — sessions, todos, subagents, observability.
+Agent PI - Agent Development Environment (ADE) for the [pi coding agent](https://pi.dev/packages/pi-kanban?name=kanban).
 
-![pi-kanban dashboard](https://raw.githubusercontent.com/NikiforovAll/pi-kanban/main/assets/pi-kanban-poster.png)
+![pi in the board terminal, with the session sidebar and a show card](https://raw.githubusercontent.com/NikiforovAll/pi-kanban/main/website/public/shots/nord/pi-terminal-light.webp)
 
-## Documentation
+## What it is
 
-**[→ See the documentation](https://nikiforovall.github.io/pi-kanban/docs/)**
+pi-kanban runs pi sessions in a browser terminal and shows each session next to its work: todos as kanban columns, subagents, linked docs, and the full session log. Its skills and its `ask` tool let the agent show you cards, ask you questions, open files and pages as tabs, and hand tasks to new pi sessions.
 
-## Try it now
+- **Documentation:** https://nikiforovall.blog/pi-kanban/
+- **Live demo:** https://nikiforovall.blog/pi-kanban/demo/ (sample sessions, runs in your browser, no install)
 
-**[→ Open the live demo](https://nikiforovall.blog/pi-kanban/)**
+## Install
 
-Click around a fully interactive dashboard with synthesized sessions, tasks, and subagents — no install. Toggle the theme, browse projects, expand a subagent's review, open the storage manager. Everything works in-browser.
-
-When you're ready to run it on your own pi sessions, install below.
-
-## Installation
+You need Node.js 20 or later and pi.
 
 ```sh
 pi install npm:pi-kanban
+npm install -g pi-kanban
 ```
 
-Then use `/kanban start | stop | restart | status | open | web | app | pin | sticky-pin | unpin | preview | link` from inside pi.
+The first command gives pi the `/kanban` command, the `ask` tool, and the skills that drive the board. The second installs the `pi-kanban` command, which runs the board.
 
-Or run standalone:
+## Start the board
 
 ```sh
-npx pi-kanban
+pi-kanban
 ```
 
-### Companion pi extensions
+The board listens on `127.0.0.1:3460` and prints its URL with the access token. Open that URL and click **+ New** to start pi in the board terminal. Start the board with `--no-terminal` to only watch sessions.
+
+When pi runs in another terminal, run `/kanban open` in pi to open the board with its token. `/kanban session open | pin | sticky-pin | unpin | view-doc | link-doc` act on the current session, and `/kanban cost` and `/kanban inspect` open pi-cost and pi-inspect for it.
+
+## The board
+
+- **Sidebar.** Sessions in groups and projects, with progress, pins, linked docs, and icons for a terminal, a dispatched session, or a question that waits for you.
+- **Terminal.** pi runs next to its board. The terminal keeps running when you close the browser tab.
+- **Board.** Pending, In Progress, and Completed columns for the selected session. Tabs next to it hold panes and show cards.
+- **New session.** Pick a folder or project, and set a name, a first prompt, the model, and the thinking level.
+- **Agents and session logs.** Subagents with model, status, and run time, and every prompt, reply, and tool call.
+- **Review.** Send review comments or card answers from the board. pi gets them as a user message.
+
+Press `?` on the board for the keyboard shortcuts.
+
+## What pi gets
 
-pi-kanban surfaces data produced by two other pi extensions. Install them alongside for the full experience:
+pi works the board through the `pi-kanban` command. The package's skills tell pi which command to run, so only the skill names and descriptions sit in the system prompt until pi needs one.
+
+| Skill | What pi does with it |
+| --- | --- |
+| `kanban` | Add a URL or a file as a tab next to the board (`pane add`, `pane list`, `pane rm`), link a file or URL to the session (`doc link`, `doc unlink`), preview a file now (`doc preview`), and open pi-cost or pi-inspect for the session (`session cost`, `session inspect`) |
+| `show` | Write a markdown or HTML card and post it with `pi-kanban show <file>`. It shows over the board terminal, or as a tab when pi runs in another terminal. |
+| `ask` | Write an HTML question for the `ask` tool |
+| `visualize` | Write a full HTML explainer page and add it as a tab |
+| `dispatch` | Hand a task to a new pi session in the board terminal (`dispatch start`) and get its report back (`dispatch wait`, `dispatch list`, `dispatch end`) |
+
+| Tool | What it does |
+| --- | --- |
+| `ask` | Show an HTML question in a modal and wait for the answer. pi asks in its own prompt when the board is down. |
+| `dispatch_report` | The worker's report, kept by the board until the parent reads it. Only a dispatched session has it. |
+
+Each session also gets a scratchpad folder, given to pi in the system prompt and in `$PI_SCRATCHPAD_DIR`. Run `pi-kanban help` for every command.
+
+## Companion pi packages
+
+pi-kanban shows data that other pi packages write:
 
 ```sh
 pi install npm:pi-subagents
 pi install npm:@juicesharp/rpiv-todo
 ```
 
-- [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) — spawns named subagent sessions; pi-kanban renders them under each parent session.
-- [`@juicesharp/rpiv-todo`](https://www.npmjs.com/package/@juicesharp/rpiv-todo) — task tracking that pi-kanban displays as kanban columns.
-- [`@juicesharp/rpiv-ask-user-question`](https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question) — pi-kanban surfaces these as interactive Q&A cards.
+- [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) starts named subagent sessions. The board shows them under each parent session.
+- [`@juicesharp/rpiv-todo`](https://www.npmjs.com/package/@juicesharp/rpiv-todo) tracks todos. The board shows them as columns.
+- [`@juicesharp/rpiv-ask-user-question`](https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question) asks you questions in the pi terminal. The board marks the session as waiting until you answer.
+
+## Security
+
+The board terminal runs commands as you, so the board is locked to your machine:
 
-## Demo
+- It listens on loopback (`127.0.0.1`) by default. `--host` changes this. Do not expose the board to a network you do not trust.
+- It refuses requests whose `Host` header is not local (`--allowed-hosts` adds names), and cross-site requests that change data.
+- Only the terminal and dispatch need the token. Anyone who can reach the board can read your pi session history, which is one more reason to keep it on loopback.
+- The terminal needs a random token. The board keeps it in the URL fragment (`#t=...`), which the browser never sends to a server. The browser keeps it in local storage, and the server keeps it across restarts in `<agent dir>/kanban/terminal-secret.json`, readable only by you. Do not share the board URL. If you did, start the board with `--new-token`.
 
+## License
 
-![pi-kanban demo](https://raw.githubusercontent.com/NikiforovAll/pi-kanban/main/assets/pi-kanban-demo.gif)
+MIT