openspec-tui

An interactive terminal UI for browsing OpenSpec workspaces — changes, their artifact pipeline (proposal → specs → design → tasks), and specs — with markdown rendered for the terminal.

It's a two-pane master/detail browser (list on the left, rendered content on the right) that reads everything through the openspec CLI's JSON API. You can read artifacts, toggle tasks, validate and archive changes, and open any artifact in your own editor.

┌ OpenSpec ◉ 3 active  ○ 1 draft  ✓ 5 done  ▪ 8 specs            my-project ─┐
│ ┌──────────────────────────┐ ┌──────────────────────────────────────────┐ │
│ │ CHANGES                  │ │  Why                                     │ │
│ │ ▸◉ add-dark-mode  45% ▓▓░ │ │  Users want to reduce eye strain and…    │ │
│ │  ○ add-user-auth         │ │                                          │ │
│ │  ✓ add-logging           │ │  What Changes                            │ │
│ │ SPECS                    │ │  • Add a theme context + CSS variables   │ │
│ │  ▪ theming        3 req   │ │  • Detect system preference              │ │
│ │                          │ │  pipeline: ✓ proposal ✓ specs ◐ design   │ │
│ └──────────────────────────┘ └──────────────────────────────────────────┘ │
│ ↑/k up  ↓/j down  ⏎/→ open  ⇥ switch pane  / filter  ? help  q quit        │
└────────────────────────────────────────────────────────────────────────────┘

• The openspec CLI must be on your PATH. The TUI shells out to it for all workspace data and actions.

  npm install -g @fission-ai/openspec

# From source
go install github.com/itslame/openspec-tui@latest

# Or build locally
git clone https://github.com/itslame/openspec-tui
cd openspec-tui
make build        # -> ./bin/openspec-tui

Prebuilt binaries for macOS/Linux (amd64/arm64) are produced by make release (into ./dist) or via GoReleaser on tagged releases.

openspec-tui            # browse the workspace nearest the current directory
openspec-tui ~/proj     # browse a specific project directory
openspec-tui --store my-store   # browse a registered OpenSpec store
openspec-tui --version

Rendering is a hybrid pipeline:

• Prose, headings, lists, tables, and code fences go through Glamour with a theme that adapts to your terminal's light/dark background and syntax-highlights code.
• OpenSpec-specific structure gets bespoke rendering:
  • tasks.md → completion markers (✓/▢), preserved grouping, and an aggregate progress bar; tasks are navigable and toggleable in place.
  • spec requirements/scenarios → cards with highlighted WHEN/THEN steps.
  • delta specs → color-coded ADDED / MODIFIED / REMOVED / RENAMED labels.

Prose is soft-wrapped and capped at a comfortable reading width even in wide terminals, and long content scrolls.

• Editor: e launches $VISUAL, falling back to $EDITOR. Multi-word values are supported, e.g. export EDITOR="code --wait" or export EDITOR=nvim. The TUI suspends while the editor runs and reloads the file on exit.
• Store: pass --store <id> to target a registered OpenSpec store instead of the nearest local openspec/ root.

make test    # go test ./...
make vet     # go vet ./...
make run     # build and launch

The codebase is split into:

• internal/openspec — the CLI adapter (subprocess + JSON decoding).
• internal/tasks — parsing/toggling tasks.md checkboxes.
• internal/render — the hybrid markdown renderer.
• internal/ui — the Bubble Tea model, update loop, and view.

MIT