Skip to content

Terminal UI

nspec includes two interactive terminal UIs built with Textual.

nspec tui       # Standard table view
nspec ngtui     # Next-gen accordion view with collapsible epic panels

Features

  • Spec Table — Multi-column sortable display with epic filtering
  • Detail Panel — Full spec metadata, tasks, and acceptance criteria
  • Real-time Search — Filter with /, navigate matches with n/N
  • Epic Filtering — Press e to filter by epic
  • Status/Priority Filtering — Press S, P, or B to filter by status, priority, or blocked state
  • Follow Mode — Auto-tracks the currently active spec (f)
  • Compact Mode — Condensed table layout (b)
  • View Cycling — Switch between table and panel layouts (v)
  • Validation Errors — Press ! to view validation errors
  • Live Reload — Watches docs directory and refreshes on changes
  • Activity Heatmap — GitHub-style commit calendar in reports view

Keybindings

Key Action
j / ↓ Move down
k / ↑ Move up
G Jump to last row
gg Jump to first row
Enter Open detail view
Escape Back / close / clear search
q Quit
Key Action
/ Open search
n Next match
N Previous match

Display

Key Action
v Cycle view mode
p Toggle detail panel
b Toggle compact mode
o Cycle sort column
O Reverse sort order
r Refresh data

Filtering

Key Action
e Set epic filter
S Filter by status
P Filter by priority
B Filter blocked specs
c Hide completed/superseded specs
C Clear all filters

Actions

Key Action
a Toggle activate spec
m Move spec to another epic
f Toggle follow mode (auto-track active spec)
s Show reports (metrics, heatmap)
h Show help
! Show validation errors
? Toggle extended footer
: Open command modal

Detail View

Press Enter on any row to open the detail view, which shows the full spec — metadata, tasks, acceptance criteria, and two always-visible dependency sections: Upstream Dependencies (specs this spec depends on) and Downstream Dependents (specs that depend on this spec).

Editing dependencies inline

You can add and remove dependencies without leaving the detail view:

Key Action
a Add a dependency — prompts for a spec ID, adds it as an upstream dep
r Remove a dependency — prompts for a spec ID to drop
d Expand/collapse the dependency lists (show all vs. the first 5)

Note: these bindings act on the detail view. In the main table, a toggles activation and r refreshes — the dependency edit keys only apply once a spec is open.

Key Action
← / h Jump to the upstream dependency (the spec this one depends on)
→ / l Jump to the downstream dependent (a spec that depends on this one)
1 / 2 / 3 Jump directly to the 1st / 2nd / 3rd direct dependency

Reading the highlighting

Each dependency line is annotated with health markers so you can spot problems at a glance:

Marker Meaning
(indirect) A transitive dependency — reached through the dep chain, not declared directly
(blocked) The dependency is itself blocked (one of its deps is incomplete)
(cycle) This spec and the dependency are mutually reachable — a dependency cycle

Direct dependencies are listed first; transitive (indirect) ones follow. Long lists are capped at 5 entries with a ... +N more (press 'd' to expand) hint — press d to see them all.

Example

The detail view's dependency sections, captured live via the Playwright terminal_* dogfooding workflow nspec uses to verify its own TUI:

 Spec S594: TUI & dependency-visualization docs
 Epic E025: Documentation Overhaul & Surface Parity
 Tasks: 2/10 (20%)

   ▼ Upstream Dependencies
  ────────────────────────────────────────────────────────────────────────────
    (<- left arrow to navigate)
      [1] S589 - Feature inventory & doc-coverage audit (

   ▼ Downstream Dependents
  ────────────────────────────────────────────────────────────────────────────
    No downstream dependents

 tab Next  shift+tab Prev  esc Close  ⏎ Toggle  ←/→ Upstream/Downstream  a Add Dep  r Remove Dep

Here S594's single upstream dependency ([1] S589) is numbered for quick 1-key navigation, and it has no downstream dependents yet. A spec whose dependencies were incomplete or mutually reachable would carry (blocked) / (cycle) markers on those lines.

Command Modal

Press : to open the command modal. Type commands to interact with specs directly from the TUI.

Engineering Metrics

Press s to access the engineering metrics dashboard:

  • Velocity — Commits, LOC, active days, specs completed per period
  • Quality — Test coverage, lint issues, cyclomatic complexity, maintainability index
  • DORA Metrics — Spec velocity tier, quality gate pass rate, change failure rate
  • Activity Heatmap — GitHub-style commit calendar

Next-Gen TUI (ngtui)

The next-gen TUI organizes specs into collapsible accordion panels grouped by epic. Each epic panel shows its specs with inline progress indicators.