openspec-ui 0.3.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.

What it does

• Dashboard — lists changes (draft / in-progress / completed / archived) with task progress bars, and specs with requirement counts.
• Kanban — a pipeline view of changes by stage, for at-a-glance status.
• Detail view — renders a change's artifacts (proposal.md, design.md, specs/**, tasks.md) read-only as markdown (ASCII diagrams and code blocks stay aligned in monospace). Switch artifacts with arrow keys.
• 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 actions.

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