@geongyu09/paseo-agent-dashboard 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 박건규 (geongyu09)
+
+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/OVERVIEW.md

@@ -0,0 +1,59 @@
+Agent board shows the agents of the current project, across its workspaces, as a live tree of cards, one card per Paseo agent. Agents started by another agent sit to the right of their parent, joined by an arrow, and pressing the arrow shows the instructions the parent sent. Open it as a workspace panel or with **Open agent board** in the Command Center.
+
+## Setup
+
+Agent board needs Paseo 0.15.3 or later and no account or settings of its own. Card titles, the **Now** line and instruction summaries come from Claude Haiku through the Claude Code CLI on the daemon machine, so Claude Code must be installed and signed in there for them. The plugin is tested on macOS. On other systems the Claude Code call may fail, and cards then fall back to Paseo's titles and the latest activity.
+
+The switch in the header (**Haiku summaries on** or **Haiku summaries off**) turns summaries on or off for every board on the host. While it is off, the plugin makes no Claude calls, and the rest of the board works the same.
+
+## Cards
+
+- Each card shows the provider icon (Claude's mark, or the OpenAI mark for Codex), the role or provider, the agent profile it matches (icon and name in the profile's color), the status, a short title, and colored tags for the model, effort and permission mode. Effort runs from green (low) to red (max). Permission modes are red for bypass or full access, amber for auto modes, blue for plan and green for modes that ask.
+- Under the tags, a bar shows how full the agent's context window was after its last turn, with the percentage and token counts. It turns amber from 50% and red from 80%.
+- Claude Haiku writes the title and the **Now** line (**Last** when the agent is not running) from the agent's last 150 timeline items. The title (up to 40 characters) says what the session works on, and **Now** (up to 60 characters) says what the agent is actually doing. Until the first summary arrives, the card shows Paseo's title and the latest tool call, answer or thought. After that, a card keeps its last summary until the next one replaces it.
+- While an agent runs, its latest tool call shows live, in the **Tool** line once a summary fills **Now**, and in **Now** itself before that. The **Step** line shows the current step of the agent's todo list when it has one.
+- While an agent compacts its context, its status reads **Compacting** in purple and the **Compact** line reads **Compacting the conversation** until the compaction ends.
+- A subagent that an agent starts inside its own session, such as one from Claude's Agent tool, gets a smaller card under that agent, joined by an arrow. The card shows **Subagent** with the subagent type, the task description, Paseo's line of model, effort and tokens, and **Working**, **Done**, **Error** or **Stopped**. Pressing it opens the agent that started it, and pressing its arrow lists the messages the subagent was given. Running subagents and the ones started since the agent's latest prompt show, and older ones show with **Ended agents (24h)** on.
+- The header counts all visible agents, the working ones, and the ones that need attention because of a pending permission or an error. Subagents are not counted.
+
+## Arrows and instructions
+
+- Side by side, the arrow joins the facing sides of the two cards at their vertical middle. With one card above the other, it leaves the parent's bottom (or top) center and enters the child's top (or bottom) center. While the child runs, the arrow turns amber and dots travel along it toward the child.
+- Pressing an arrow, or the button in its middle, opens an **Instructions sent** box over that button. It lists the messages the parent agent sent the child, oldest first, read from the child's whole timeline. **First instruction** is the delegation and the follow-ups come after it. Your own prompts to the child are not listed.
+- With summaries on, each instruction shows Haiku's goal and up to five main points, and **Show original** unfolds the text as sent. With summaries off, the original shows. The box header names both agents, by their summarized titles when summaries are on.
+- Pressing anywhere on the board outside the box closes it. The buttons and the box sit above the cards. On desktop and web, the box keeps its size at any zoom and opens on the side of the button with more room, so it stays inside the board.
+
+## Layout and navigation
+
+- The **Group by workspace** switch (on by default) stacks each workspace's graphs together and draws a dashed, lightly tinted box around them, with the workspace name and its labels in their Paseo colors on top. Boxes follow cards you drag, and dragging a box moves every card of its workspace together.
+- Drag a card to move it, and press it briefly to open the agent. Hold Shift while dragging to snap the card to another card's left or top edge, one tree gap beside, above or below a card, or else to a 20px grid. Positions are saved per agent on the host, so they stay after the tab is closed. **Reset layout** puts the moved cards back in the tree layout.
+- Scroll or swipe to move around the board in any direction (Shift + wheel moves sideways). Zoom from 25% to 150% around the pointer with Ctrl or ⌘ + scroll, or a trackpad pinch. In the mobile app the board scrolls instead and does not zoom. Position and zoom reset when the tab reopens.
+- ⌘Z or Ctrl+Z, with the pointer over the board, undoes the last card move, workspace move or layout reset, up to 50 steps.
+- The **Ended agents (24h)** switch also shows agents that were closed or archived in the last 24 hours, dimmed with a dashed border.
+- The crosshair on a card highlights that agent with its ancestors and descendants and dims the rest, and the eye button hides that agent with its descendants. **Clear highlight** in the header removes the highlight, and another header button shows the hidden agents again. These view settings are kept per tab.
+
+## Languages and themes
+
+The board follows the app language and is available in English, Korean and Simplified Chinese. Other app languages show English. Haiku writes summaries in the app language, with about half the characters in Korean, Japanese and Chinese, and a new app language gets new summaries.
+
+On light themes, cards, arrow buttons and the instruction box keep the dark Ghostty colors, while the background, header and workspace boxes follow the theme.
+
+## Data access
+
+The board reads the project's agents, their timelines, the workspaces and the host's agent profiles through Paseo. Card positions and the summary switch are saved in the plugin's host settings, and the other view settings in the tab.
+
+Summaries run Claude Code in print mode (`claude -p`) with the Haiku model on the daemon machine, from a temporary folder, with no tools, settings, MCP servers or saved session. They use your Claude usage. Each card summary sends the agent's Paseo title and up to about 6,000 characters of its newest activity to Anthropic through Claude Code. That activity is prompts and instructions (up to 400 characters each), agent answers (up to 300), tool calls with their shell commands, short file paths, search queries and URLs (up to 200), todo items, and errors (up to 200). A running agent is summarized at most once a minute, and a stopped one only when its timeline has changed since the last summary.
+
+Opening an instruction box with summaries on also sends each listed instruction, up to its first 8,000 characters, for a summary. This happens once per instruction text and app language while the plugin runs, and a failed call is tried again the next time the box shows that instruction. At most two Claude calls run at once, and each one stops after 60 seconds. Summaries are kept in memory only and are lost when the plugin reloads.
+
+For subagent cards, the plugin's server connects to the daemon on its own machine, at the `daemon.listen` address in the Paseo home's `config.json`, and reads the subagents of the shown agents and the messages each subagent was given. It reads them every 2 seconds while an agent or a subagent runs, and every 20 seconds otherwise.
+
+To color workspace labels, the plugin reads Paseo's label file, `projects/workspace-labels.json` in the Paseo home folder (`~/.paseo` unless `PASEO_HOME` is set), on the daemon machine. It uses only each label's name and color. If the file cannot be read, labels are gray.
+
+## Limits
+
+- Paseo does not record which profile started an agent, so a card shows the profile whose provider and fixed settings (model, permission mode, effort) all equal the agent's current ones. An agent set up by hand like a profile shows that profile, and one whose mode or effort changed afterwards shows none.
+- Closed and archived agents are hidden unless **Ended agents (24h)** is on.
+- Paseo's plugin API has no subagent list, so the plugin connects to the daemon on its own machine for subagent cards. A daemon that needs a password or listens on a socket shows no subagent cards.
+- New agents take their tree position and can overlap a card you moved.
+- Dragging is meant for desktop. On touch devices it can conflict with scrolling.

package/OVERVIEW.zh-CN.md

@@ -0,0 +1,59 @@
+智能体看板以实时卡片树显示当前项目各工作区中的智能体，每个 Paseo 智能体对应一张卡片。由其他智能体启动的智能体位于父智能体右侧，以箭头相连，点按箭头即可查看父智能体发送的指令。可以作为工作区面板打开，也可以在命令中心选择 **打开智能体看板**。
+
+## 设置
+
+智能体看板需要 Paseo 0.15.3 或更高版本，本身不需要账号或设置。卡片标题、**当前** 行和指令总结由 Claude Haiku 通过守护进程所在机器上的 Claude Code CLI 生成，因此需要在该机器上安装并登录 Claude Code。插件已在 macOS 上测试。在其他系统上，Claude Code 调用可能失败，此时卡片会改为显示 Paseo 的标题和最新活动。
+
+标题栏中的开关（**Haiku 总结已开启** 或 **Haiku 总结已关闭**）会为主机上的所有看板开启或关闭总结。关闭时插件不会调用 Claude，看板的其他功能照常可用。
+
+## 卡片
+
+- 每张卡片显示提供方图标（Claude 的标志，Codex 则为 OpenAI 的标志）、角色或提供方、匹配到的智能体配置（以配置的颜色显示图标和名称）、状态、简短标题，以及模型、推理强度和权限模式的彩色标签。推理强度从绿色（低）到红色（最高）。权限模式中，绕过或完全访问为红色，自动模式为琥珀色，计划模式为蓝色，需要确认的模式为绿色。
+- 标签下方的进度条显示智能体上一轮结束后上下文窗口的占用程度，并给出百分比和 token 数。达到 50% 时变为琥珀色，达到 80% 时变为红色。
+- Claude Haiku 根据智能体最近 150 条时间线记录生成标题和 **当前** 行（智能体未运行时为 **最后**）。标题（最多 40 个字符）说明本次会话在做的工作，**当前**（最多 60 个字符）说明智能体实际正在做什么。第一份总结到达之前，卡片显示 Paseo 的标题以及最新的工具调用、回答或思考。之后，卡片会保留上一份总结，直到新的总结取而代之。
+- 智能体运行时，其最新的工具调用会实时显示。总结填入 **当前** 后，它显示在 **工具** 行，在此之前直接显示在 **当前** 行。智能体有待办列表时，**步骤** 行显示当前步骤。
+- 智能体压缩上下文时，状态显示为紫色的 **压缩中**，**压缩** 行显示 **正在压缩对话记录**，直到压缩结束。
+- 智能体在自己的会话中启动的提供方子智能体（例如 Claude 的 Agent 工具启动的子智能体）会在该智能体下方显示为一张较小的卡片，并以箭头相连。卡片显示 **子智能体** 和子智能体类型、任务说明、Paseo 给出的模型、推理强度和 token 数，以及 **工作中**、**已完成**、**出错** 或 **已中断**。点按卡片会打开启动它的智能体，点按它的箭头会列出该子智能体收到的消息。运行中的子智能体和在智能体最近一条提示之后启动的子智能体会显示，更早的子智能体在打开 **已结束的智能体（24 小时）** 时显示。
+- 标题栏统计所有可见的智能体、正在工作的智能体，以及因待处理的授权或出错而需要处理的智能体。子智能体不计入统计。
+
+## 箭头和指令
+
+- 两张卡片左右并排时，箭头在两张卡片相对一侧的垂直中点处连接。一张卡片在另一张上方时，箭头从父卡片底部（或顶部）中点出发，进入子卡片顶部（或底部）中点。子智能体运行时，箭头变为琥珀色，并有圆点沿箭头流向子智能体。
+- 点按箭头或其中间的按钮，会在该按钮旁打开 **已发送的指令** 框。框中按时间先后列出父智能体发给子智能体的消息，内容读取自子智能体的完整时间线。**首条指令** 是委派任务的指令，之后是追加指令。你自己发给子智能体的提示不会列出。
+- 开启总结时，每条指令显示 Haiku 总结的目标和最多五个要点，**查看原文** 可展开发送时的原文。关闭总结时直接显示原文。框的标题栏会写出两个智能体的名称，开启总结时使用总结后的标题。
+- 点按框外看板上的任意位置即可关闭该框。按钮和框位于卡片之上。在桌面端和网页端，框在任何缩放比例下都保持原有大小，并在按钮周围空间较大的一侧打开，因此不会超出看板。
+
+## 布局和导航
+
+- 打开 **按工作区分组** 开关（默认开启）时，同一工作区的图会堆叠在一起，外面画有浅色填充的虚线框，框顶部以 Paseo 颜色显示工作区名称及其标签。框会跟随你拖动的卡片，拖动框会让该工作区的所有卡片一起移动。
+- 拖动卡片可以移动它，短按卡片可以打开智能体。拖动时按住 Shift，卡片会对齐到另一张卡片的左边缘或上边缘，或另一张卡片旁边、上方、下方一个树间距的位置，否则对齐到 20px 网格。位置按智能体保存在主机上，关闭标签页后依然保留。**重置布局** 会把移动过的卡片放回树状布局。
+- 滚动或滑动可以向任意方向移动看板（Shift + 滚轮横向移动）。按住 Ctrl 或 ⌘ 滚动，或在触控板上捏合，可以围绕指针在 25% 到 150% 之间缩放。在移动端应用中，看板改为滚动，不能缩放。重新打开标签页时，位置和缩放会重置。
+- 指针位于看板上时，按 ⌘Z 或 Ctrl+Z 可撤销上一次卡片移动、工作区移动或布局重置，最多 50 步。
+- 打开 **已结束的智能体（24 小时）** 开关后，还会显示过去 24 小时内关闭或归档的智能体，这些卡片会变暗并带有虚线边框。
+- 卡片上的十字准星按钮会高亮该智能体及其祖先和后代，并使其余卡片变暗；眼睛按钮会隐藏该智能体及其后代。标题栏中的 **取消高亮** 可以取消高亮，另一个标题栏按钮可以重新显示隐藏的智能体。这些视图设置按标签页保存。
+
+## 语言和主题
+
+看板跟随应用语言，支持英语、韩语和简体中文。其他应用语言显示英语。Haiku 使用应用语言撰写总结，韩语、日语和中文的字数约为一半，切换应用语言后会生成新的总结。
+
+使用浅色主题时，卡片、箭头按钮和指令框保持 Ghostty 的深色配色，背景、标题栏和工作区框则跟随主题。
+
+## 数据访问
+
+看板通过 Paseo 读取项目的智能体及其时间线、工作区以及主机上的智能体配置。卡片位置和总结开关保存在插件的主机设置中，其他视图设置保存在标签页中。
+
+总结在守护进程所在机器上以打印模式（`claude -p`）运行 Claude Code，使用 Haiku 模型，从临时文件夹启动，不加载任何工具、设置或 MCP 服务器，也不保存会话。总结会消耗你的 Claude 用量。每次卡片总结会通过 Claude Code 把智能体的 Paseo 标题和最多约 6,000 个字符的最新活动发送给 Anthropic。这些活动包括提示和指令（每条最多 400 个字符）、智能体回答（最多 300 个）、工具调用及其 shell 命令、简短文件路径、搜索词和 URL（最多 200 个）、待办事项，以及错误（最多 200 个）。运行中的智能体最多每分钟总结一次，已停止的智能体只有在上次总结后时间线发生变化时才会再次总结。
+
+在开启总结时打开指令框，还会发送框中列出的每条指令（最多取前 8,000 个字符）以生成总结。插件运行期间，每条指令文本在每种应用语言下只总结一次，调用失败时，下次框中显示该指令时会重试。同时最多运行两个 Claude 调用，每个调用 60 秒后停止。总结只保存在内存中，插件重新加载后即丢失。
+
+为了显示子智能体卡片，插件的服务端会连接同一台机器上的守护进程，地址为 Paseo 主目录中 `config.json` 的 `daemon.listen`，并读取所显示智能体的子智能体，以及每个子智能体收到的消息。有智能体或子智能体在运行时每 2 秒读取一次，否则每 20 秒读取一次。
+
+为了给工作区标签着色，插件会读取守护进程所在机器上的 Paseo 标签文件，即 Paseo 主目录中的 `projects/workspace-labels.json`（未设置 `PASEO_HOME` 时为 `~/.paseo`）。插件只使用每个标签的名称和颜色。无法读取该文件时，标签显示为灰色。
+
+## 限制
+
+- Paseo 不记录智能体由哪个配置启动，因此卡片显示的是提供方及其固定设置（模型、权限模式、推理强度）都与智能体当前设置相同的配置。手动按某个配置设置的智能体会显示该配置，之后更改过模式或推理强度的智能体不显示任何配置。
+- 除非打开 **已结束的智能体（24 小时）**，否则已关闭和已归档的智能体会被隐藏。
+- Paseo 的插件 API 没有子智能体列表，因此插件会为子智能体卡片自行连接同一台机器上的守护进程。需要密码或通过套接字监听的守护进程不会显示子智能体卡片。
+- 新的智能体会放在树状布局中的默认位置，可能与你移动过的卡片重叠。
+- 拖动主要面向桌面端。在触屏设备上，拖动可能与滚动冲突。

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# Agent board
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agent board is a Paseo plugin that shows the agents of the current project as a live tree of cards. Each card shows the agent's status, provider, model, effort, permission mode and context use. Agents started by another agent sit beside their parent, joined by an arrow, and pressing the arrow shows the instructions the parent sent. Subagents an agent starts inside its own session, such as those from Claude's Agent tool, get smaller cards under it. Optional summaries from Claude Haiku give each card a short title and a line about what the agent is doing now. See [OVERVIEW.md](OVERVIEW.md) for the full description, including what data is sent where.
+
+![Agent board](assets/board-dark.webp)
+
+## Install
+
+Once the plugin is listed in the Paseo plugin registry:
+
+```bash
+paseo plugin add geongyu09/paseo-agent-dashboard
+```
+
+From npm, which works now:
+
+```bash
+paseo plugin add npm:@geongyu09/paseo-agent-dashboard
+```
+
+## Requirements
+
+- Paseo 0.15.3 or later.
+- For Haiku summaries, the Claude Code CLI installed and signed in on the daemon machine. Summaries can be turned off with the switch in the board header, and the board works without them.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+paseo plugin install /absolute/path/to/paseo-agent-dashboard
+paseo plugin reload paseo-agent-dashboard
+```
+
+Run `paseo plugin reload paseo-agent-dashboard` after each change to load it into the daemon.
+
+## Languages
+
+The board is available in English, Korean and Simplified Chinese, and follows the app language.
+
+## Credits
+
+The Claude and OpenAI marks come from [Simple Icons](https://simpleicons.org) under CC0-1.0. Claude is a trademark of Anthropic, and OpenAI is a trademark of OpenAI. Their use does not imply endorsement.
+
+## License
+
+MIT. See [LICENSE](LICENSE).