hermes-kanban-tui
A read-only terminal view of the Hermes Kanban board, built to run inside
herdr panes in Ghostty. Install it as
hermes-kanban-tui; the command it puts on your PATH is kanban-tui.
Not affiliated with Nous Research. It reads the board their hermes CLI writes
and never writes to it beyond the one comment action described below.
kanban-tui # current board, status columns
kanban-tui --all # include done + archived history
kanban-tui --status blocked # start filtered
kanban-tui --pane # open in a fresh herdr workspace
kanban-tui --json # machine-readable board, then exit
kanban-tui --print 160x48 # one frame as text, then exit
kanban-tui --where # print what it resolved, then exit
kanban-tui --mouse # click to select, wheel to scroll
kanban-tui --no-write # disable the comment action
Keyboard first, no build step, no dependency on Linux or macOS. Read-only: it never writes to the board.
Install
No dependencies, one module. Pick whichever you already use:
pipx install hermes-kanban-tui # isolated, puts kanban-tui on PATH
uv tool install hermes-kanban-tui
pip install --user hermes-kanban-tui
From a checkout, without installing anything:
git clone https://github.com/kylernunan/hermes-kanban-tui
cd hermes-kanban-tui
./kanban-tui --where
Requires Python 3.10+. curses ships with Python on Linux and macOS; on Windows
pip pulls in windows-curses for you, and if it is ever missing the interactive
view says so instead of crashing while --print, --json and --where keep
working. The interactive view is only tested on Linux and macOS. The pane-title
and mouse features assume a Unix terminal.
It reads the board the Hermes CLI reads: ~/.hermes/kanban.db, HERMES_HOME,
HERMES_KANBAN_HOME, or --db, in that order of specificity. --where prints
exactly what it resolved before you look at a blank screen.
Installed or checked out, the flags are identical: the shell script only finds
the module and picks an interpreter, every option lives in kanban_tui.py.
Why it exists
hermes kanban list is a good script surface and a poor dashboard: it prints
one status at a time, one screen at a time, and nothing refreshes. The board
also carries evidence the CLI summaries drop -- which run a card is on, when it
last sent a heartbeat, how close it is to its runtime limit, why it blocked, and
which cards are gated by unfinished parents. This view shows all of it on one
screen, answers "what needs me now" per card, and leaves the board untouched.
Read-only by design, with one comment path
The viewer opens kanban.db with mode=ro (falling back to query_only=1 on a
second handle if a hot WAL refuses a read-only open) and issues only SELECTs.
The single exception is the comment action, and even that does not write SQL: it
runs hermes kanban comment as a subprocess, so the CLI remains the only writer
on the board.
There is no claim, unblock, complete, reassign, promote or dispatch path in the
code. --no-write removes the comment action as well, for a display that must
not mutate anything.
Proved by test: TestCli.test_db_is_byte_identical_after_snapshot and
TestLiveBoard.test_live_snapshot hash kanban.db before and after a run and
require the bytes to match.
What is on screen
Two layouts over the same selection. Wide panes get the board; narrow panes get
the list. b switches between them at any width.
BOARD (default at >= 96 cols and >= 18 rows)
row 0 board name, per-status counts, refresh interval, clock
row 1 filters: open/history, status, assignee, search, listed count
columns one column per status, left to right in workflow order:
triage, todo, scheduled, ready, running, review, blocked
(+ done, archived with 'd'), each headed by its count
cards id, a why-it-is-not-moving signal, age, and up to two wrapped
title lines
strip the selected card underneath: run, heartbeat, claim, block kind,
failure, then body / events / comments
LIST (narrow panes, or 'b')
left the same tasks as one scrolling list grouped by status
right the same detail, side by side instead of underneath
Column widths follow load: every column keeps a 16-cell floor, the remaining cells are shared in proportion to how many cards each holds, and no column takes more than 40 so one busy status cannot swallow the board. On the live board that gives blocked (13 cards) 31 cells and the empty running column 17, instead of 24 each.
Columns stay in a fixed workflow order so a card moving status moves sideways
rather than shuffling the board. An empty column still shows its count; when the
pane is too narrow for all of them the empty ones are dropped first, and only
then does the board page a window that follows the cursor (< / > in the
column headers mark the hidden side).
Done and archived hold 917 rows between them, which no column can show. Those
two columns load the most recent --history-cap cards (default 25), ordered by
completion time, and the header keeps the true total ("done 860"). When a spare
row exists the column ends with "+N older". A selected card that falls outside
the loaded window is pulled back into view rather than silently disappearing.
The signal on a card
Six cells that answer "why is this not moving", so a card never needs opening to be triaged:
!cap blocked on a capability wall (no access, no credential)
!need blocked needing an owner decision
!dep blocked on a dependency that is itself unfinished
!trns blocked on a transient failure
!block blocked with no typed reason
depN N parents are still open, so nothing can run it yet
hbNNs running, heartbeat this recent
!hb ... running, heartbeat is stale (over 120s)
The card's id line is coloured by severity: red for blocked or a stale heartbeat, yellow for a dependency wait. A selected card keeps the reverse cursor style so the position is never ambiguous.
On this board that surfaces real state: 13 blocked cards split 6 !cap,
3 !need, 4 !block, and 10 open cards that are silently waiting on open
parents (one on five).
Detail tabs:
1 body markdown-ish body, wrapped to at most 100 columns so prose
stays readable in a very wide pane
2 events the task_events stream with payload summarised
3 comments full comment thread
Keys
j k move between tasks / down and up the current column
h l board only: previous / next column (skips empty ones)
g G first / last card in the column
Space u page down / page up
Tab Enter switch focus between the board (or list) and the detail
1 2 3 detail tab: body / events / comments (also focuses detail)
z show or hide the detail strip / pane
b switch between the board and the list view
s S cycle status filter forward / back
a A cycle assignee filter forward / back
/ search id, title, assignee (Enter apply, Esc cancel)
d show or hide done + archived
r refresh now
p pause / resume auto refresh
? help
q quit
Commenting (the only write)
c comment on the selected card
Enter post Esc cancel Ctrl-U clear
The compose line shows the target card, and posting runs exactly one command:
hermes kanban comment <task_id> --author kanban-tui <text>
The text is passed as a single argv element, so a semicolon, backtick or $(...)
in a comment is stored literally rather than interpreted. The view itself never
writes SQL: kanban.db is opened read-only and the only mutation goes through
the CLI, which keeps one writer on the board. After a successful post the view
refreshes and switches the detail to the comments tab.
A failed post keeps your text in the compose line and reports the error, so it
can be retried rather than retyped. --no-write removes the action entirely;
--author NAME changes the recorded author.
Deliberately absent: claim, unblock, complete, reassign, promote and dispatch. Those change what the dispatcher picks up, so they stay in the CLI where the confirmation lives.
Mouse (opt-in, and gated by herdr)
kanban-tui --mouse
Click a card to select it, click empty space in a column to jump to its first card, right-click does the same, double-click selects and focuses the detail, wheel moves the selection or scrolls the detail when it has focus. Off by default: a pane that captures the mouse steals drag-select and the terminal's own scrollback, so you choose it per run.
Inside herdr there is a second gate that is not ours: herdr is mouse-native and
captures the mouse for its own UI (ui.mouse_capture, default true), so a
plain click selects herdr panes and drags borders instead of reaching the app.
Herdr's docs are explicit about the switch:
# ~/.config/herdr/config.toml
[ui]
mouse_capture = false
Turning it off gives the pane the mouse and gives up herdr's click-to-focus, drag-borders, right-click menus and drag-select copy. The narrower option is per-pane right-click forwarding, which keeps herdr's left-click UI:
herdr pane input <pane> --right-click pane
Both are herdr settings, not this program's. The app side is proved by
herdr_mouse_probe.py, which delivers a click through herdr's own terminal API
and requires the cursor to move.
herdr and Ghostty
Ghostty's terminfo. Ghostty sets TERM=xterm-ghostty. The stock
ncurses-term package on this box ships a ghostty entry but not
xterm-ghostty, so ncurses programs die with setupterm: could not find terminal. Two independent defenses:
kanban_tui.pyprobes terminfo at startup and falls back toxterm-256colorwhen the exported name has no entry, reporting the substitution in the help screen. Verified by running with an emptyTERMINFOdirectory (seedocs/VERIFICATION.md).install-terminfo.shinstalls a realxterm-ghosttyentry into~/.terminfoby rewriting the header of the shippedghosttyentry. User-local, no sudo, and--checkreports state without changing anything.
Pane title. Inside a herdr pane (HERDR_ENV=1 and HERDR_PANE_ID set) the
view publishes kanban <board>: N running, N ready, N blocked as pane metadata
through herdr pane report-metadata, so the workspace tab strip carries crew
state while the pane is in the background. The title is cleared on exit -- a
quit board must not keep advertising counts. Any herdr error is recorded and
shown in the help screen; it never takes the board down. --no-herdr disables
it entirely.
Flicker. paint() diffs rows against the previous frame and rewrites only
what changed, so a steady board writes almost nothing to the pane instead of
repainting 48 rows every two seconds.
Snapshot mode
Two non-interactive modes, no TTY needed:
./kanban-tui --print 160x48 # one frame as text
./kanban-tui --json # the filtered board as JSON
./kanban-tui --json --status blocked # machine-readable, scripted
--json emits {"schema": "hermes-kanban-tui/1", generated_at, board, db, filters, counts, task_count, tasks[]}. Each task carries id, title, status,
assignee, priority, timestamps, age, open_parents, workspace_path, the
block object (kind, recurrences, consecutive failures, last failure) when
blocked, current_run (id, profile, status, elapsed, runtime limit, heartbeat
age) when running, and the same signal / severity the card shows. Filters
apply. It never writes.
That is the surface Fleet, HQ or a watchdog can consume without parsing column text.
Output is a fixed-size character grid: exactly H lines, no line wider than W
display cells. That invariant is asserted across eight sizes in
TestRendering.test_frame_matches_requested_size. Narrow-layout tests cover the
30-81 column tier: Tab swaps panes, all three detail tabs are reachable, and no
row overflows at 70x30, 49x38 or 30x12.
Layout tiers
The frame degrades instead of breaking:
>= 96 cols and >= 18 rows board: status columns + detail strip
< 96 cols or < 18 rows list; >= 82 cols keeps list and detail side by side
30-81 cols list with one pane at a time: Tab swaps
list <-> detail, 1/2/3 jumps to a detail tab
< 30 cols list only
< 12 rows filter line dropped
< 10 rows single-line footer
Board columns need ~16 cells each, which is why the board starts at 96 for the
seven open statuses. b overrides the automatic choice in either direction.
The one-pane list tier exists because a herdr pane split two ways is often ~49 columns wide, and a detail pane that cannot be reached is the same as no detail pane. Verified at 49x38 live, and down to 20x5 overall.
Files
kanban_tui.py the viewer (stdlib only, no install)
kanban-tui launcher: board resolution, --pane, --where
install-terminfo.sh add the xterm-ghostty terminfo entry
test_kanban_tui.py 122 tests, fixture board + live-board smoke test
pty_drive.py run the TUI in a real pty and capture every byte
ansi_screen.py turn those bytes back into the visible grid
resize_probe.py SIGWINCH at four sizes, report any overflow
refresh_probe.py insert into a board copy, prove live refresh works
mouse_probe.py click a card in a real pty, prove the cursor moves
herdr_mouse_probe.py click through herdr's terminal API, inside a pane
comment_probe.py type a comment into a board copy, read it back
verify.sh every check above, PASS/FAIL per stage
tests/golden-*.txt stored frames: board 160x40, board 100x24, list 70x26
docs/VERIFICATION.md the commands run and what they returned
docs/screen-148x40.txt a captured board frame, for diffing a layout change
Tests
./verify.sh # unit tests + every probe, PASS/FAIL per stage
./verify.sh --quick # unit tests only
python3 -m unittest test_kanban_tui -v
Fixture tests cover geometry (wide characters, control characters, exact
padding), the read-only guarantee, ordering, every key binding, filter cycling,
search, the herdr bridge's enabled/disabled/error paths, and the CLI. The
live-board test runs only when ~/.hermes/kanban.db exists.
mouse_probe.py does the same for pointer input: it locates a card in the
rendered frame, writes a mouse report into the pty the way a terminal would, and
requires the selection to move to that card. It tries SGR (1006) and the legacy
X10 encoding; ncurses accepted both here.
pty_drive.py plus ansi_screen.py are the end-to-end proof: a real pty, a
real window size, real keystrokes, and the resulting screen reconstructed from
the captured bytes. Unit tests cannot see a curses crash on startup; that pair
can.
tests/golden-*.txt are whole frames at three geometries (board 160x40, board
100x24 where empty columns drop, list 70x26). They pin the picture, not just the
facts: a change that keeps every field but moves it on screen still fails. The
clock and absolute dates are normalised out, and App.render(now=...) takes an
injectable clock so a frame is reproducible. After an intended layout change:
KANBAN_TUI_UPDATE_GOLDEN=1 python3 -m unittest test_kanban_tui.TestGoldenFrame
and read the diff before committing to it.
Notes
~/.hermes/kanban.dbis thedefaultboard. Named boards live at~/.hermes/kanban/boards/<slug>/kanban.db;--board <slug>resolves them.~/.hermes/kanban/kanban.dbexists but is a zero-byte file -- the viewer refuses it rather than showing an empty board.- Auto-refresh is 2s by default (
--interval). One tick is three query sets (counts, open tasks, parent-wait/live-run maps) and runs in ~12 ms on a 23 MB board with 950 tasks. - The elapsed clock on a finished run is measured to
ended_at, so a completed run does not keep ageing.
Metadata
Release files for hermes-kanban-tui 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hermes_kanban_tui-1.0.2.tar.gz | 78.6 kB | With provenance | Details for hermes_kanban_tui-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hermes_kanban_tui-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for hermes_kanban_tui-1.0.2-py3-none-any.whl |
Total release size: 112.3 kB
Release files / hermes_kanban_tui-1.0.2.tar.gz
| Download URL | hermes_kanban_tui-1.0.2.tar.gz |
|---|---|
| Size | 78.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
713be98af4f091a6d8fb54c38cdac6c83922a823aad7acb4c44aa74b588d56f7
|
|
BLAKE2b-256 checksum How to use checksums |
a4bf342dbd2294f25180a6c7bea06378b8023690c68b51356f40705d8a224abe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / hermes_kanban_tui-1.0.2-py3-none-any.whl
| Download URL | hermes_kanban_tui-1.0.2-py3-none-any.whl |
|---|---|
| Size | 33.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
40fc72b104f8e3a7f4ff1973509ca4cdf956c4982e975645475acbe65fd43aef
|
|
BLAKE2b-256 checksum How to use checksums |
db4be52757e8aeabda2d0df214edba5559f4d383390d58b2dfdd0c94469bfc69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for hermes-kanban-tui 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for hermes_kanban_tui-1.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.