@gbasin/agentboard

中文文档
0.46.8发布于 2026/11/15MITES Module构建来源已验证近 30 天下载 7293

Web GUI for tmux optimized for AI agent TUIs

原始使用文档
文档目录23 节
  1. Features
  2. Status and last prompt for every session
  3. Subagent activity
  4. Pull requests with CI state
  5. Media from the transcript
  6. History, Hibernate, and Wake
  7. On your phone
  8. Sessions from other machines
  9. Also
  10. Supported agents
  11. Requirements
  12. Install
  13. Homebrew
  14. npm
  15. Open the board
  16. Run it as a service
  17. Upgrade
  18. Uninstall
  19. From source
  20. Configuration
  21. Keyboard shortcuts
  22. How it works
  23. Documentation

Agentboard

CI npm License: MIT TypeScript Ask DeepWiki

Agentboard is a web UI for tmux, built for running coding agents such as Claude Code and Codex. Start your agents on a desktop or server, then watch and steer them from any browser, including your phone.

Every session lives in tmux, so your agents keep running when you close the tab, and the same sessions are available from every device.

Agentboard in a desktop browser window, with a phone in front of it. The desktop sidebar lists agent sessions with their status, age, last prompt and pull request chips; one session waits for permission. The terminal shows a Claude Code session refactoring a router, with a Media 2 pill in its corner. The phone shows the same session's terminal with a quick-keys toolbar.

The same tmux sessions on a laptop and a phone.

Features

Status and last prompt for every session

Each session shows a status inferred from its terminal output: working, waiting for input, or needs permission. Sessions matched to an agent transcript also show the last prompt you sent. Optional sounds tell you when a session needs permission or goes idle.

Animation: the sidebar lists sessions with their last prompts and ages. The selected session, orders-migration, shows a permission prompt to run a database migration; its status badge changes to a raised hand while the prompt is open, then back to now when the prompt is answered.

Subagent activity

For local Claude Code and Codex sessions, a counter on the session shows how many subagents are running. Click it to see the main session and each subagent with its current state and the time of its last activity signal.

The agent activity panel for the router-refactor session, opened from its subagent counter showing 3. The main session has an active model turn. Of four subagents, Migrate billing routes and Run e2e suite are waiting on Edit and Bash tool calls, Migrate invoice routes has an active model turn, and Audit auth middleware has finished.

Pull requests with CI state

Pull requests that a session created with gh pr create or through the GitHub connector appear as chips on the session, colored by state: open, draft, merged, or closed. Claude Code sessions also show pull requests that Claude Code linked to the session, such as one it pushed to. Hover a chip to see its title and CI checks.

Four sidebar sessions with pull request chips: a draft (489), two open (482 and 1193) and a merged one (1187). A hover card for pull request 1193 shows its title and four CI checks, one of them failing.

Media from the transcript

A media rail collects the images, documents, and links from a session's transcript. Open any image in a viewer and step through the rest.

The media rail open over a session's terminal: tabs for Media 5 and Links 1, then thumbnails for a PDF report, a search results screenshot, a CPU flame graph and two latency charts. Below it, the transcript lines where the agent read those files.

History, Hibernate, and Wake

Hibernate closes an agent session's tmux window and keeps its conversation in the sidebar. It works for local sessions in the tmux session that Agentboard manages. History lists recent conversations: open one to preview its transcript, then Wake it to resume.

The transcript preview of a past Claude Code conversation, admin-react-19, about upgrading an app to React 19, with Cancel and Wake buttons.

On your phone

On a small screen the board switches to a touch layout: a session drawer, a quick-keys toolbar (Esc, Tab, Ctrl, arrow keys, numbers), and a paste dialog. Touch scrolling, tap-to-click, and long-press selection work in the terminal. Add the board to your home screen as a PWA.

Three phone screens. Left: the session drawer listing sessions with status, last prompt and pull request chips. Middle: a session waiting on a permission prompt, with a row of numbered session tiles at the top and the quick-keys toolbar at the bottom. Right: the paste dialog with three lines of text ready to submit.

Sessions from other machines

Sessions from other machines appear on the same board over SSH, with a host badge on each one. Filter the board by host or by project. See Remote hosts.

Five sidebar sessions from two machines: rows badged STUDIO run locally, rows badged BUILD-BOX run on a remote host. The remote Codex session nightly-e2e is selected.

Also

  • A full terminal in the browser. Mouse scrolling, selection, and the clipboard work with Claude Code's fullscreen renderer.
  • Paste or drop text, images, and files into the prompt.
  • Keyboard shortcuts to switch, create, and close sessions.
  • Sort by age or by what needs attention, filter by project or host, or drag sessions into your own order.
  • Session recovery lists the sessions that a crash or reboot interrupted, so you can reopen them. Automatic reopening is opt-in. See Session recovery.

Supported agents

AgentMatching, last prompt, WakePull requestsMedia railSubagent activity
Claude CodeYesYesYesYes
CodexYesYesYesYes
PiYesYesLinks
oh-my-piYesYesLinks
Devin CLIYesYesLinks
Grok CLIYesYesLinks

The media rail shows images, documents, and links for Claude Code and Codex. For the other agents it shows links.

Agentboard finds each agent's transcripts in its default location and matches them to tmux windows automatically. Any other program that runs in tmux also works as a plain terminal session, with status but no transcript features.

Requirements

  • macOS (Apple Silicon or Intel) or Linux (x64 or arm64).
  • tmux 3.2 or later: brew install tmux or apt install tmux.
  • ripgrep (rg): brew install ripgrep or apt install ripgrep. Agentboard uses it to match agent transcripts to tmux windows. The Homebrew and npm packages do not install it.
  • Tailscale (recommended) or another network path to your machine, for access from other devices.

Optional:

  • The GitHub CLI (gh), signed in, to show pull request state and CI checks.
  • ssh with key-based access, to show sessions from remote hosts.

Install

Homebrew

brew tap gbasin/tap
brew install agentboard
agentboard

npm

Requires Node.js 18 or later.

npm install -g @gbasin/agentboard
agentboard

Or run it without installing:

npx @gbasin/agentboard

Open the board

Open http://localhost:4040 on the same machine.

If Tailscale is running, Agentboard also listens on your Tailscale address. Open http://<your-machine>:4040 from any device on your tailnet. To install the board on your phone's home screen, see PWA installation.

Without Tailscale, Agentboard accepts connections from the same machine only. To change that, see Network and security.

Run it as a service

To start Agentboard at login and keep it running:

Both installers need a git checkout of this repository. They do not use a Homebrew or npm install.

Upgrade

Run brew upgrade agentboard or npm install -g @gbasin/agentboard@latest, then restart Agentboard. Your tmux sessions keep running across the restart, and your data stays in ~/.agentboard.

These commands do not upgrade a service installed with the launchd or systemd installer. Upgrade a service as its guide describes.

Uninstall

Stop Agentboard, then run brew uninstall agentboard or npm uninstall -g @gbasin/agentboard.

brew uninstall also removes tmux if no other formula needs it. To keep tmux, run HOMEBREW_NO_AUTOREMOVE=1 brew uninstall agentboard.

If you installed a service, remove it first. For that, and for the data and settings that an uninstall leaves in place, see Uninstall.

From source

See Development.

Configuration

Agentboard is configured with environment variables. It has no command-line flags.

PORT=8080 TMUX_SESSION=work agentboard
VariableDefaultEffect
PORT4040Port for the web UI.
HOSTNAME127.0.0.1Address to bind. Set 0.0.0.0 to listen on all interfaces.
TMUX_SESSIONagentboardName of the tmux session that Agentboard manages.
DISCOVER_PREFIXESunsetLimits which of your other tmux sessions appear on the board. By default, all of them appear.
AGENTBOARD_REMOTE_HOSTSunsetSSH hosts to show on the board.
AGENTBOARD_DATA_DIR~/.agentboardDirectory for the database and logs.

See Configuration for every setting.

Appearance, notification sounds, command presets, session list options, and terminal options are in the Settings dialog in the UI.

Security note: Agentboard has no authentication. Anyone who can reach the server can run commands as your user. By default it accepts connections from this machine and, if Tailscale is running, from your tailnet. Do not set HOSTNAME=0.0.0.0 on a network that you do not trust (public Wi-Fi, a shared LAN) without another access control layer. See SECURITY.md for the full threat model.

Keyboard shortcuts

ActionMacWindows/Linux
Previous sessionCtrl+Option+[Ctrl+Shift+[
Next sessionCtrl+Option+]Ctrl+Shift+]
Jump to session 1-9Ctrl+Option+1..9Ctrl+Shift+1..9
New sessionCtrl+Option+NCtrl+Shift+N
Kill sessionCtrl+Option+XCtrl+Shift+X
SettingsCtrl+Option+,Ctrl+Shift+,

To use a different modifier, open Settings > Terminal.

How it works

┌─────────────┐    SSH     ┌─────────────┐
│ Remote Host ├───────────►│             │   WebSocket   ┌────────────┐
│ (tmux)      │            │  Agentboard ├──────────────►│  Browser   │
└─────────────┘    tmux    │  Server     │               │  (React +  │
┌─────────────┐    CLI     │             │               │  xterm.js) │
│ Local tmux  ├───────────►│  - discover │               └────────────┘
│ sessions    │            │    sessions │
└─────────────┘            │  - parse    │
┌─────────────┐    read    │    agent    │
│ Agent logs  ├───────────►│    logs     │
│             │            └─────────────┘
└─────────────┘
  • Session discovery: The server polls local tmux windows and, if you configure them, remote hosts over SSH.
  • Status inference: The server reads pane content to tell if each agent is working, waiting for input, or asking for permission.
  • Log matching: The server reads agent transcripts to match each session to its tmux window and to show its last prompt, pull requests, and media.
  • Live terminal: The server streams terminal I/O to the browser, so you can use any session from any device.
  • Hibernating and History sessions: The sidebar keeps dormant agent sessions, and you wake one when you need it. Startup does not wake hibernating or History sessions.

Documentation

版本与发布记录

@gbasin/agentboard 共发布 198 个版本,首次发布于 2026/02/07;过去 12 个月发布了 198 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.46.8latest2026/11/151 天前
0.46.72026/11/142 天前
0.46.62026/11/132 天前
0.46.52026/11/132 天前
0.46.42026/11/133 天前
0.46.32026/11/133 天前

关于 @gbasin/agentboard 的常见问题

@gbasin/agentboard 是什么?

Web GUI for tmux optimized for AI agent TUIs

如何安装 @gbasin/agentboard?

在项目目录运行 npm install @gbasin/agentboard,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agentboard,可以用 npx agentboard 直接运行。

@gbasin/agentboard 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gbasin__agentboard 是否存在。

@gbasin/agentboard 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gbasin/agentboard 可以商用吗?

@gbasin/agentboard 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gbasin/agentboard 的下载量有多少?

根据 npm 官方下载统计,@gbasin/agentboard 在 2026/10/16 – 2026/11/14 这 30 天内被下载 7,293 次,日均约 243 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gbasin/agentboard 还在维护吗?

最新版本 0.46.8 发布于 2026/11/15(1 天前);至今共发布 198 个版本,其中过去 12 个月发布了 198 个;首次发布于 2026/02/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。