# Agentboard reads your agent logs to tell working from waiting from blocked

> Agentboard is a browser front end for tmux built around agent TUIs, so a Claude, Codex or Pi session can be watched and driven from a phone over Tailscale. The interesting parts are the ones a tmux wrapper does not usually have: status inferred from JSONL logs rather than from the pane, a hibernate mode that closes the tmux window but keeps the session listed, no authentication at all, and four prebuilt platform packages with no Windows build.

**gbasin/agentboard** — Web GUI for tmux optimized for AI agent TUIs, with support for iOS safari and mac w/ keyboard shortcuts

- Repository: https://github.com/gbasin/agentboard
- Stars: 418 · Forks: 47
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/gbasin-agentboard

## Status comes from JSONL logs, not from the pane

The three features that separate this from a tmux theme are log parsing, session matching and hibernation.

Status inference is the first. The server reads pane content and the Claude and Codex JSONL logs to decide whether a session is working, waiting for input, or asking for permission. That is a three state answer derived from files on disk rather than from screen scraping, which means an agent sitting at a permission prompt is distinguishable from an agent that has finished and is idle. A sidebar that cannot tell those apart is just a list of windows.

Session discovery is the second. It polls local tmux windows and, optionally, remote hosts over SSH, and the log tracking is automatic: sessions are matched to active tmux windows for Claude, Codex and Pi, with one-click Wake for sessions that are hibernating or in history. The diagram in the README shows the three paths into the server, SSH from a remote host that runs tmux, the tmux CLI for local sessions, and a plain read of agent logs under `~/.claude/`.

What the user sees is deliberately small: the last user prompt for each session, so you can remember what each agent was doing, and a live terminal that streams I/O through the server to any device. A fullscreen Claude Code renderer is on by default, with mouse scrolling, click handling, in-app selection and clipboard forwarding through the browser terminal.

## No authentication, so the bind address is the whole security model

The security note is the most important paragraph in the README, and it does not soften anything. Agentboard has no built-in authentication. Anyone who can reach the server has full access to the terminal sessions, including the ability to run commands as your user.

What makes that survivable is the default bind address. `HOSTNAME` controls which interfaces the server binds to, and it defaults to `127.0.0.1` for localhost only. With that default in place, if Tailscale is detected the server also binds to your Tailscale IP automatically, which is the intended remote access path, since Tailscale provides the network level authentication that the application itself does not. Setting it to `0.0.0.0` listens on all interfaces, and the README says plainly to avoid that on untrusted networks such as public WiFi or a shared LAN without putting an access control layer in front.

There is a second subtlety in the same variable, and it catches people running in containers. A `HOSTNAME` that merely equals the machine hostname is treated as auto exported by the environment, which containers and some CI images do, and it is ignored with a warning, which keeps the localhost default in place. So a value that looks like an explicit choice can be silently discarded.

Everything else in the environment block is a switch with a default, and the defaults lean towards doing nothing destructive.

## Hibernate closes the tmux window and keeps the session listed

Hibernating is a tmux window that has been closed while the session stays visible. The README's phrasing is that hibernating a session closes its tmux window but keeps it visible across restarts for a manual Wake, and the sidebar keeps both hibernating and history sessions around, waking them on demand. Startup deliberately does not auto-wake dormant sessions, which is the right default: an agent that wakes itself at boot and starts editing a repository is not what anyone wants.

The related variables are the ones that keep the tmux server tidy. `PRUNE_WS_SESSIONS`, on by default, removes orphaned `agentboard-ws-*` tmux sessions at startup, and can be set to `false` to disable that. `DISCOVER_PREFIXES` decides which windows from other tmux sessions get discovered and controlled; in the example it is `work,external`, and if it is unset every session except the managed one is discovered.

Two reserved names are worth knowing. Windows named `__agentboard_root__` are always hidden, because that name belongs to the placeholder that keeps a base session alive. And `ALLOW_KILL_EXTERNAL` defaults to `false`, so a session discovered from outside the managed set cannot be killed from the UI unless you opt in. A kill shortcut exists in the keyboard table, and the default is the reason an external session survives an accidental keystroke.

Other defaults: `PORT=4040`, `TMUX_SESSION=agentboard`, `REFRESH_INTERVAL_MS=5000`, `AGENTBOARD_INACTIVE_MAX_AGE_HOURS=24`, a SQLite database at `~/.agentboard/agentboard.db`, and `AGENTBOARD_EXCLUDE_PROJECTS` defaulting to an empty value plus `/workspace`.

## The npm package ships a launcher, not the application

The npm package is `@gbasin/agentboard`, and what it publishes is thin. The `files` array contains `bin/**/*` and `README.md`, so the tarball carries the `agentboard` launcher and a readme. The application arrives through four optional dependencies, `@gbasin/agentboard-darwin-arm64`, `@gbasin/agentboard-darwin-x64`, `@gbasin/agentboard-linux-x64` and `@gbasin/agentboard-linux-arm64`, each pinned to the same version as the launcher, 0.22.1 in the current package.json.

So there are three supported platforms and no Windows entry, which is a strange thing to find in a project whose own keyboard table has a Windows and Linux column. The install routes follow from that structure, and there are three:

```bash
brew tap gbasin/tap
brew install agentboard
agentboard
```

```bash
npm install -g @gbasin/agentboard
agentboard
```

or no install at all with `npx @gbasin/agentboard`. Either way the server comes up on port 4040 and you open `http://localhost:4040`.

Working from source needs Bun 1.3.14 or later, which is also the `engines` field in package.json and the reason a `.bun-version` file sits at the top of the repository. `bun install` then `bun run dev` gives you a Vite dev server on 5173, and `bun run build` followed by `bun run start` serves the built UI from the backend port, 4040, so the two ports only exist during development.

## A dependency scanner that fails locally harder than CI does

There is a built-in risk scanner for direct dependencies, with a human output and a machine one:

```bash
bun run deps:risk
```

```bash
bun run deps:risk:json
```

The policy behind it is spelled out, which is the useful part. Security risk comes from `bun audit --json` findings, aggregated by severity into low, moderate, high and critical. Maintenance risk comes from `bun outdated`, classifying how far behind latest a version is as major, minor or patch.

Then the thresholds diverge, and this is the bit to notice. The local default threshold is `high`, so high and critical findings fail your run. CI enforces security threshold breaches at `critical` only, through `bun run deps:risk:ci`, while existing upstream high advisories are merely tracked, and maintenance findings are warnings for prioritisation. A developer running the scanner by hand is held to a stricter bar than the pipeline, on the stated grounds that high advisories already known upstream should not block a merge.

The threshold is overridable, either as an argument or through an environment variable:

```bash
bun run deps:risk -- --threshold moderate
```

The same package.json shows the rest of the tooling: oxlint for linting, `tsc --noEmit` for types, a custom test runner at `scripts/test-runner.ts` with a `--skip-real-tmux` mode for CI, coverage with lcov, and Playwright for end to end tests with a headed variant.

## The iOS Safari work is the actual differentiator

The mobile list is longer than the feature list of most terminal GUIs, and it is the part that has no equivalent elsewhere. Paste support including images, touch scrolling, tap to click, and long press selection in fullscreen Claude Code sessions. Mobile friendly copy prompts for the cases where a browser clipboard write needs a user gesture and therefore cannot happen silently. A virtual arrow keys d-pad, and a quick keys toolbar for the keys a terminal user reaches for constantly, ctrl and esc among them.

Each of those exists because a phone browser is a hostile terminal. Long press selection is the fix for a selection model built around a mouse, the copy prompt is the fix for a clipboard API that requires a gesture, and the d-pad is the fix for a keyboard that is not under your fingers. None of them are hard, and all of them are the difference between using an agent from a phone and not.

The keyboard table covers the desktop case with separate Mac and Windows or Linux bindings, since the same five actions need different chords on each:

| Action | Mac | Windows/Linux |
| --- | --- | --- |
| Previous session | `Ctrl+Option+[` | `Ctrl+Shift+[` |
| New session | `Ctrl+Option+N` | `Ctrl+Shift+N` |
| Kill session | `Ctrl+Option+X` | `Ctrl+Shift+X` |

The README also has a Desktop table and a Mobile table further down, and both are empty apart from their headers, which is where the screenshots would go.

## Three release files and a release every few hours

The top level is a busy one for a project of this size, and most of the entries explain themselves. `release-please-config.json` and `.release-please-manifest.json` are the pair that automates version bumps and changelog entries, and the release history shows the result: v0.21.1 on 30 September 2026, v0.22.0 on 1 October, and v0.22.1 on the same day a few hours later, with the last push to master dated 1 October 2026. Three releases inside two days is what a project shipping to its own users with a release bot looks like.

`prepare` runs `git config core.hooksPath .githooks`, which is how the hooks directory at the root gets wired up without asking anyone. `oxlint.json` holds the lint configuration, `playwright.config.ts` the end to end configuration, `tailwind.config.js` and `postcss.config.js` the styling pipeline, and `bun.lock` and `bunfig.toml` the dependency lock and runtime config.

Then there is the deployment documentation, with a `systemd/README.md` for Linux and a `launchd/README.md` for macOS, both pointed at twice in the install section for people who want the server to survive a reboot. `docs/`, `notes/`, `tools/`, `npm/`, `public/`, `assets/`, `bin/` and `src/` are the working directories, and the process files sit alongside them: `AGENTS.md`, `CLAUDE.md`, `CHANGELOG.md`, `CONTRIBUTING.md` is absent, and `SECURITY.md` is present. The README also links a DeepWiki page for the project.

## Conclusion

Agentboard suits someone running several agent sessions on a machine they can reach, who wants one sidebar on a phone instead of a second laptop. It does not suit a shared host on an untrusted network, because the project states plainly that there is no authentication and anyone who reaches the server can run commands as your user. Before installing, read the HOSTNAME default and leave it at 127.0.0.1 unless Tailscale is in place, check that a prebuilt package exists for your platform since only macOS and Linux binaries are published, and remember that npm installs a launcher script rather than the application itself.

## FAQ

### What is Agentboard and how does it know what an agent session is doing?

It is a web GUI for tmux built for agent TUIs such as claude and codex. Status inference reads pane content together with the Claude and Codex JSONL logs to decide whether a session is working, waiting for input, or asking for permission, and sessions are auto-matched to active tmux windows.

### Does Agentboard have authentication on its web interface?

No. The README states there is no built-in authentication and that anyone who can reach the server has full access to the terminal sessions, including running commands as your user. The default HOSTNAME binding of 127.0.0.1 keeps it on localhost, and Tailscale is recommended because it provides the network level authentication the app does not.

### How do I install Agentboard, and what does the npm package contain?

Use brew tap gbasin/tap followed by brew install agentboard, or npm install -g @gbasin/agentboard, or npx @gbasin/agentboard. The npm tarball itself contains only the bin directory and the README, with the application arriving through four optional platform packages for macOS and Linux on both architectures.

### What do hibernating and history sessions do in Agentboard?

Hibernating closes a session's tmux window while keeping it visible in the sidebar, and it can be woken on demand with one click, including after a restart. Startup does not auto-wake dormant sessions, and orphaned agentboard-ws-* tmux sessions are pruned at startup unless PRUNE_WS_SESSIONS is set to false.

### What does the Agentboard dependency risk scanner check?

Security risk comes from bun audit --json findings aggregated by severity, and maintenance risk comes from bun outdated, classifying version lag as major, minor or patch. The local default threshold is high, while CI only fails at critical, and the threshold can be changed with --threshold or DEPENDENCY_RISK_FAIL_ON.

## Sources

- [gbasin/agentboard on GitHub](https://github.com/gbasin/agentboard)
- [Issues](https://github.com/gbasin/agentboard/issues)
- [License: MIT](https://github.com/gbasin/agentboard/blob/master/LICENSE)
- [README](https://github.com/gbasin/agentboard/blob/master/README.md)
- [Releases](https://github.com/gbasin/agentboard/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gbasin-agentboard