lazy-openspec

A lazygit/lazydocker-style terminal UI for OpenSpec. Browse changes and specs, read artifacts rendered beautifully, tick off tasks, and run the OpenSpec workflow commands — all from one keyboard-driven screen.

┌─[1]─Changes──────────┐┌─ add-user-auth ─────────────── active · 3/5 ─┐
│ Active               ││ proposal · specs · design · tasks            │
│▸◉ add-user-auth  60% ││                                              │
│ Draft                ││ 1. Backend auth              ██████░ 2/3     │
│ ○ add-data-export    ││   ✔ 1.1 Add user model                       │
├─[2]─Specs────────────┤│ ▸ ☐ 1.3 Issue session tokens                 │
│ ▪ auth        4r     ││                                              │
├─[3]─Archive──────────┤│ 2. Frontend                  ░░░░░░░ 0/2     │
│ ▫ old-migration      ││   ☐ 2.1 Build login form      scroll 40% ────│
└──────────────────────┘└──────────────────────────────────────────────┘
┌─ Command log ────────────────────────────────────────────────────────┐
│ $ openspec validate add-user-auth → ✓ completed                      │
└──────────────────────────────────────────────────────────────────────┘
 [ ] artifact  space toggle  v validate  esc back  ? help

Why

OpenSpec's built-in openspec view is a one-shot printout. lazy-openspec is a full interactive TUI: stacked, numbered panels on the left (Changes, Specs, Archive), a rendered detail pane on the right, and a command-log/hint bar at the bottom. Artifacts are rendered readably — Glamour for prose, and semantic rendering of OpenSpec's structures (requirements, WHEN/THEN scenarios, task checklists).

Install

Requires the openspec CLI on your PATH — lazy-openspec shells out to it.

go install github.com/itslame/lazy-openspec/cmd/lazy-openspec@latest
# or from a clone:
make install

Usage

Run it inside a directory that has an openspec/ root:

lazy-openspec
lazy-openspec --store <id>   # target a registered OpenSpec store

Keybindings

Key	Action
tab / shift+tab, 1–3	switch / jump between panels
↑/↓, j/k	move selection (or scroll)
enter	open the selected change or spec
[ / ], ←/→	switch artifact tab (proposal · specs · design · tasks)
space	toggle the selected task (tasks tab), persisted to tasks.md
n / p	next / previous requirement (spec view)
v	run openspec validate
a	show openspec apply instructions
A	run openspec archive (with confirmation)
x	actions menu
r	refresh
?	help overlay
esc	back
q / ctrl+c	quit

Architecture

• internal/openspec — data-access layer: shells out to openspec … --json (list, status, show, spec show), decodes tolerantly, caches results.
• internal/render — Glamour prose rendering + semantic renderers for requirements, scenarios, and task checklists (with a monochrome NO_COLOR fallback).
• internal/tasks — parses tasks.md and performs the byte-preserving checkbox toggle.
• internal/tui — the Bubble Tea models, Lip Gloss layout, and the streaming command runner.

Refresh on focus

lazy-openspec refreshes itself when the terminal regains focus, so if an agent or a CLI in another pane edits openspec/ while you are away, switching back shows current data — the lists and the open preview — without pressing r. Nothing is polled or fetched while the terminal is blurred, and your selection and scroll position are preserved across the refresh.

This relies on terminal focus reporting (DEC mode 1004), supported by iTerm2, kitty, WezTerm, Alacritty, Ghostty, and Windows Terminal. Inside tmux it also needs:

set -g focus-events on   # ~/.tmux.conf

On terminals that do not report focus, no events arrive, nothing breaks, and r remains the manual refresh (which also reloads the preview, not just the lists).

Notes

• a shows apply instructions rather than "running apply": there is no openspec apply CLI command — apply is an AI-driven step (e.g. the /opsx:apply skill). The a key surfaces openspec instructions apply, the real affordance.
• Tested against openspec (@fission-ai/openspec) 1.5.0.

Development

make test    # unit + (skippable) live integration tests
make vet
make build   # -> bin/lazy-openspec

Built with Go, Bubble Tea, Lip Gloss, and Glamour.