openspec-ui 0.4.0

An unofficial, community-built interactive TUI for visualizing and managing OpenSpec changes and specs. Not affiliated with Fission-AI/OpenSpec.

openspec-ui

Unofficial. openspec-ui is a community-built tool and is not affiliated with, endorsed by, or sponsored by Fission-AI/OpenSpec. It consumes the openspec CLI over subprocess as a third-party client.

An interactive, keyboard-driven terminal UI for visualizing and managing your OpenSpec changes and specs.

openspec view dumps a static dashboard and exits. openspec-ui is the interactive version: browse changes and specs, glance at progress, see a kanban pipeline of your changes, open artifacts, edit them in $EDITOR, and create new changes — all from one terminal command.

Install & run

uvx openspec-ui

Run it from inside any directory containing an openspec/ root (or a subdirectory of one). Requires the openspec CLI on PATH.

Requires Python 3.10+ and Textual 1.0 or newer (installed automatically).

What it does

• Dashboard — an aligned table of changes (stage, name, progress, tasks, last modified) over headline counts of specs and of changes per stage. Specs are listed with their requirement counts.
• Kanban — a pipeline view of changes by stage, each column and card carrying that stage's colour, for at-a-glance status.
• Change detail — renders a change's artifacts (proposal.md, design.md, specs/**) as scrollable markdown with a navigable table of contents; ASCII diagrams and code blocks stay aligned in monospace. When an artifact resolves to several files, each gets its own tab.
• Tasks — a change's tasks.md rendered as its checklist, one section per heading with a done/total count. Read-only; edits go through $EDITOR.
• Spec browser — open a spec to read its overview and requirements, each expandable to reveal its scenarios.
• Filter — press / to narrow the changes and specs by name.
• Edit — press e to open the current artifact in $EDITOR; the view reloads from disk when the editor exits.
• New change — press n to create a change via openspec new change.
• Command palette — Ctrl+P for fuzzy-searchable actions, including jumping straight to any change or spec by name, and switching theme.
• Live refresh — open views re-read from disk as things change on disk; press p to pause.

Keys

Press ? at any time for the bindings available on the current screen.

Key	Does
?	Show key bindings for the current screen
Ctrl+P	Command palette (actions, jump to change/spec, theme)
/	Filter the current listing by name (escape clears)
enter	Open the selected change or spec
k / d	Kanban / dashboard
n	New change
e	Edit the current artifact in $EDITOR
r	Refresh now
p	Pause or resume live refresh
t	Toggle the table of contents (change detail)
q	Quit

Theming

openspec-ui ships no palette of its own — all colour comes from the active Textual theme, so it follows your terminal. Switch themes in-session from the command palette (Ctrl+P → Theme). Nothing is written to disk: the app persists no state, theme included.

Design

openspec-ui is a thin client: it owns no state. Every read comes from openspec ... --json or direct file reads under openspec/; every write is delegated to the openspec CLI or to $EDITOR. This keeps the view layer replaceable (a future SvelteKit web UI could reuse the same data contract).

Status

Alpha. Built with Textual. Supports OpenSpec CLI 1.7.x (@fission-ai/openspec).

Releases

Releases are fully automated. Maintainers never edit the version field by hand.

1. Conventional commits land on main (via PRs).
2. On each push to main, CI runs commitizen (cz bump --yes --changelog), which determines the next semver from the commit log, updates version in pyproject.toml, updates CHANGELOG.md, and creates/pushes a v<version> tag.
3. The tag push triggers a second CI job that builds the wheel+sdist and publishes them to PyPI using trusted publishing (OIDC) — no stored API tokens.
4. feat:/fix:/breaking commits release; pure chore:/docs: commits do not (commitizen determines there is no increment).

Trusted publisher setup (one-time, manual)

Before the publish job works, register a trusted publisher on pypi.org once:

• PyPI project: openspec-ui (create it if it does not yet exist).
• GitHub repo: mrn-dk/openspec-ui.
• Workflow filename: .github/workflows/release.yml.
• Environment name: pypi (the publish job uses environment: pypi).

This is a web step on pypi.org that cannot be automated from within the repo. Until it is done, the publish job will fail with an OIDC error; the build artifacts still exist in the workflow run and can be uploaded manually.

The first release also needs a seeded v0.1.0 tag (commitizen bumps relative to an existing tag); after that, cz bump always has a reference.

Contributing

This project follows the OpenSpec spec-driven workflow (openspec/).

Git history uses Conventional Commits and conventional branch names:

• Branches: feat/<scope>, fix/<scope>, refactor/<scope>, chore/<scope>, …
• Commits: feat:, fix:, docs:, refactor:, chore:, … (with a scope when helpful, e.g. feat: add kanban view).
• Never commit directly to main. Work on a dedicated branch and open a pull request with the GitHub CLI (gh pr create), referencing the OpenSpec change name in the PR description.

For changes managed through OpenSpec, see openspec/config.yaml for the project context and per-operation guidance that the openspec skills follow.

License

MIT