Skip to content
/
Tier B A8 Cross-runtime harness

OpenSpecUI (jixoai)

openspec-ui-jixoai · jixoai/openspecui · ★ 72 · last commit 2026-05-26

Provide a visual web interface for OpenSpec workflows with PTY terminal, OPSX compose, project hooks, and static export.

Best whenThe OpenSpec CLI remains the source of truth; the UI adds a projection layer that can customize display without modifying source files.
vs seeds
openspecseed. It extends the seed's CLI with a visual dashboard, multi-tab PTY term…
Primitive shape 20 total
Commands 10 Skills 10
00

Summary

OpenSpecUI (jixoai) — Summary

OpenSpecUI is the official web interface for the OpenSpec spec-driven development workflow, maintained by jixoai. It ships as a monorepo npm package (openspecui) with a CLI binary that launches a local web server on port 3100. The UI provides a dashboard for specs/changes/tasks status, a config/schema viewer and editor, an OPSX compose panel for change actions, a multi-tab PTY terminal (xterm + ghostty-web), and static snapshot export for documentation hosting. OpenSpecUI 3.x targets OpenSpec CLI 1.3.x and tracks its minor version line. A key extensibility mechanism is project-local hooks (openspec/openspecui.hooks.ts) with two typed hooks: onReadDocument (transforms markdown before UI display) and onRunWorkflow (adjusts OPSX invocation payloads). The package also ships 10 slash commands and 10 skills that expose the full OpenSpec lifecycle (new change, apply, archive, verify, etc.) in Claude Code.

differs_from_seeds: OpenSpecUI is the most complete OpenSpec ecosystem companion: it combines the UI dashboard role (like specboard), the workflow skill set (like openspec seed), a local terminal, and a static export pipeline. The closest seed is openspec itself (same maintainer lineage), but openspecui adds the PTY terminal, OPSX compose panel, project hooks for document projection, and multi-tab UI that the OpenSpec CLI alone does not provide.

01

Overview

OpenSpecUI (jixoai) — Overview

Origin

Maintained by jixoai (Fission AI), the same organization behind the OpenSpec CLI. OpenSpecUI major versions track OpenSpec CLI minor versions (UI 3.x → CLI 1.3.x). The repo has multiple legacy READMEs documenting the evolution from v0.16 through v1.x, v1.2, and v1.3+.

Philosophy

From the README: "OpenSpecUI is a web interface for OpenSpec workflows (live mode + static export)."

The system is designed to be the human-friendly layer on top of the OpenSpec CLI. It provides both a live interactive mode (local web server) and a static export mode for documentation hosting. Project hooks let teams customize how documents are projected to UI consumers without modifying source files.

Manifesto-style statements

  • "OpenSpec CLI remains the source of truth for workflow status, instructions, schemas, validation, and archive behavior."
  • "Source reads stay raw and audit-safe, so editing, validation, and source inspection still use the original OpenSpec files."
  • "If a hook throws, OpenSpecUI falls back to the default result and attaches diagnostics instead of blocking the UI."

Version compatibility matrix

OpenSpecUI OpenSpec CLI
@latest / @^3 >=1.3.0 <1.4.0 (accepted: >=1.2.0)
@^2 >=1.2.0 <1.3.0
@^1 >=1.0.0 <1.2.0

Target user

Teams and individuals using the OpenSpec CLI workflow who want a rich web UI for browsing, executing, and exporting their spec-driven development content.

02

Architecture

OpenSpecUI (jixoai) — Architecture

Distribution

  • npm package: openspecui (not namespaced)
  • Also installable via Nix flake: nix run github:jixoai/openspecui

Install methods

npx openspecui@latest         # run without global install (recommended)
bunx openspecui@latest        # same via bun
npm install -g openspecui     # global install
nix run github:jixoai/openspecui -- --help

CLI binary

Binary: openspecui

openspecui [path] [--port N]
openspecui export -o ./dist [--base-path /docs] [--clean]
openspecui --help

Monorepo package structure

packages/
├── ai-provider/         # AI provider abstraction
├── app/                 # Application shell (Cloudflare Workers)
├── browser-translator/  # Browser-based translation
├── cli/                 # openspecui CLI package
├── core/                # Core types + logic
├── local-translator/    # Local document translation
├── openai-completion-translator/  # OpenAI completion
├── search/              # Full-text search
├── server/              # Express-like server
├── web/                 # Main web frontend
├── website/             # Marketing site
└── xterm-input-panel/   # PTY terminal input panel

Tech stack

  • Runtime: Node.js + Bun (dev tools)
  • Frontend: React 19 + TypeScript (implied from devDependencies)
  • Terminal: xterm + ghostty-web (multi-tab PTY)
  • Build: tsdown (CLI bundle)
  • Test: vitest
  • Package manager: pnpm@10.22.0

Required runtime

Project hooks file

openspec/openspecui.hooks.ts — project-local hooks for document projection and OPSX invocation customization

03

Components

OpenSpecUI (jixoai) — Components

Claude Code Commands (.claude/commands/opsx/)

Command Purpose
opsx:apply Implement tasks from an OpenSpec change
opsx:archive Archive a completed OpenSpec change
opsx:bulk-archive Archive multiple completed changes
opsx:continue Continue generating artifacts for a change
opsx:explore Explore the OpenSpec project context
opsx:ff Fast-forward a change (generate all artifacts in one step)
opsx:new Start a new change
opsx:onboard Onboard a new project to OpenSpec
opsx:sync Sync spec deltas
opsx:verify Verify a change's completeness

Claude Code Skills (.claude/skills/)

Skill Purpose
openspec-apply-change Autonomous version of apply-change command
openspec-archive-change Autonomous version of archive
openspec-bulk-archive-change Autonomous bulk archive
openspec-continue-change Autonomous continue artifact generation
openspec-explore Autonomous explore
openspec-ff-change Autonomous fast-forward
openspec-new-change Autonomous new change creation
openspec-onboard Autonomous onboarding
openspec-sync-specs Autonomous spec sync
openspec-verify-change Autonomous verify

UI features (web dashboard)

  • Dashboard: specs/changes/tasks status overview
  • Config/Schema viewers and editors
  • OPSX compose panel for change actions
  • Multi-tab PTY terminal (xterm + ghostty-web)
  • Search (live mode + static mode)
  • Static snapshot export for docs hosting

Project hooks

  • onReadDocument: OnReadDocumentHookV1 — transforms markdown before display (add glossary, translate, add derived context)
  • onRunWorkflow: OnRunWorkflowHookV1 — adjusts OPSX invocation payload (e.g., append project policy text)

MCP configuration

.mcp.json present in repo root (content not fetched; likely configures MCP servers for the development environment).

05

Prompts

OpenSpecUI (jixoai) — Prompts

Verbatim excerpt 1: openspec-apply-change SKILL.md

---
name: openspec-apply-change
description: Implement tasks from an OpenSpec change. Use when the user wants to start
  implementing, continue implementation, or work through tasks.
license: MIT
compatibility: Requires openspec CLI.
metadata:
  author: openspec
  version: '1.0'
  generatedBy: '1.2.0'
---

Implement tasks from an OpenSpec change.

**Input**: Optionally specify a change name. If omitted, check if it can be inferred from
conversation context. If vague or ambiguous you MUST prompt for available changes.

**Steps**

1. **Select the change**
   If a name is provided, use it. Otherwise:
   - Infer from conversation context if the user mentioned a change
   - Auto-select if only one active change exists
   - If ambiguous, run `openspec list --json` to get available changes and use the
     **AskUserQuestion tool** to let the user select

   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).

2. **Check status to understand the schema**
   ```bash
   openspec status --change "<name>" --json

Parse the JSON to understand:

  • schemaName: The workflow being used (e.g., "spec-driven")
  • Which artifact contains the tasks

  1. Get apply instructions

    openspec instructions apply --change "<name>" --json

    This returns:

    • Context file paths (varies by schema)
    • Progress (total, complete, remaining)
    • Task list with status
    • Dynamic instruction based on current state

    Handle states:

    • If state: "blocked" (missing artifacts): show message, suggest openspec-continue-change
    • If state: "all_done": congratulate, suggest archive
    • Otherwise: proceed to implementation

**Prompting technique**: CLI-orchestration pattern — skill invokes CLI tools and uses their JSON output to branch logic. Uses `AskUserQuestion` tool for disambiguation. Schema-aware: different artifact structures for different workflow schemas.

---

## Verbatim excerpt 2: `opsx:new` command

```markdown
---
name: 'OPSX: New'
description: Start a new change using the experimental artifact workflow (OPSX)
---

Start a new change using the experimental artifact-driven approach.

**Input**: The argument after `/opsx:new` is the change name (kebab-case), OR a description
of what the user wants to build.

**Steps**

1. **If no input provided, ask what they want to build**
   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
   > "What change do you want to work on? Describe what you want to build or fix."
   From their description, derive a kebab-case name.
   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.

2. **Determine the workflow schema**
   Use the default schema (omit `--schema`) unless the user explicitly requests a different workflow.
   **Use a different schema only if the user mentions:**
   - A specific schema name → use `--schema <name>`
   - "show workflows" or "what workflows" → run `openspec schemas --json` and let them choose
   **Otherwise**: Omit `--schema` to use the default.

3. **Create the change directory**
   ```bash
   openspec new change "<name>"

  1. Show the artifact status

    openspec status --change "<name>"

  2. Get instructions for the first artifact

    openspec instructions <first-artifact-id> --change "<name>"

  3. STOP and wait for user direction


**Prompting technique**: Clarification-first gate ("Do NOT proceed without understanding") + schema discovery pattern + explicit stop point that hands control back to human.
09

Uniqueness

OpenSpecUI (jixoai) — Uniqueness & Positioning

differs_from_seeds

OpenSpecUI is the official companion UI for the openspec seed framework. Where the openspec seed provides CLI + Claude Code commands/skills for workflow execution, OpenSpecUI adds: a visual web dashboard with real-time status, a multi-tab PTY terminal for direct CLI access, an OPSX compose panel for point-and-click workflow execution, project-local hooks for document projection without modifying source files, and a static export pipeline. The openspec seed's 11 commands and 11 skills are mirrored here with additional commands (ff, bulk-archive, onboard) not present in the seed. The version-tracking relationship (UI major → CLI minor) shows this is a maintained companion, not an independent fork.

Positioning

  • Category: OpenSpec ecosystem — official full-stack companion UI
  • User: Teams using OpenSpec who want a visual workflow interface beyond the CLI
  • Integration: Primary — requires OpenSpec CLI as runtime backend; Claude Code skills/commands are secondary interface
  • Value: Web dashboard + PTY terminal + OPSX compose panel + static export + project hooks

Observable failure modes

  1. Version compatibility gating: UI shows "OpenSpec CLI Required" and blocks interactions if CLI version is outside >=1.2.0 <1.4.0 — teams running legacy CLI versions are blocked
  2. pnpm workspace complexity: Monorepo with 12 packages, pnpm@10.22.0 required — higher contribution barrier than single-package tools
  3. Hook TypeScript compilation: openspecui.hooks.ts requires TypeScript knowledge; install-time types needed from openspecui/hooks
  4. onRunWorkflow only adjusts payload, doesn't control execution: Teams wanting full workflow overrides must still use the CLI
  5. Project-specific: The openspec:check-reference script suggests tight coupling to specific project conventions

Cross-references

  • Official companion to: openspec (seed framework)
  • Related: specboard (this batch, also a dashboard but focused on kanban/Conductor), spek (read-only viewer)
  • Extended by: intellij-openspec (this batch, which adds IntelliJ IDE integration for the same workflow)
  • opcode-plugin-openspec (this batch) adds OpenCode integration
04

Workflow

OpenSpecUI (jixoai) — Workflow

Live mode workflow

Phase Actor Action Artifact
1 — Start Human openspecui [./my-project] Web server at localhost:3100
2 — Browse Human Navigate dashboard in browser Status overview
3 — Execute action Human Click OPSX compose panel → trigger action onRunWorkflow hook fires → OpenSpec CLI invoked
4 — View result Human See changes reflected in UI Updated specs/changes/tasks
5 — Terminal Human Use multi-tab PTY terminal Direct CLI access within UI

Static export workflow

Phase Actor Action Artifact
1 Human openspecui export -o ./dist Static HTML snapshot
2 CI/Human Deploy ./dist to docs hosting Publicly accessible snapshot

Claude Code workflow (commands/skills)

Phase Actor Action Artifact
1 — Plan Agent /opsx:new <name> New change scaffolded
2 — Generate Agent /opsx:ff <name> or /opsx:continue Artifacts generated
3 — Implement Agent /opsx:apply <name> Tasks implemented
4 — Verify Agent /opsx:verify <name> Completeness check
5 — Archive Agent /opsx:archive <name> Change archived

Approval gates

The opsx:apply skill halts if state: "blocked" (missing upstream artifacts) and suggests running openspec-continue-change. Otherwise mostly autonomous.

Phase-to-artifact map

Phase Artifact
new-change openspec/changes/<name>/ scaffolded
continue / ff proposal.md, design.md, specs/, tasks.md
apply Implemented code matching tasks
verify Completeness report
archive openspec/changes/archive/<name>/
06

Memory Context

OpenSpecUI (jixoai) — Memory & Context

State storage

  • UI config: openspec/.openspecui.json — persisted UI configuration (tab state, preferences)
  • Project hooks: openspec/openspecui.hooks.ts — project-local behavior customization
  • OpenSpec files: openspec/changes/, openspec/specs/ — authoritative state (managed by CLI)

What the UI persists

The README explicitly separates concerns: "Hooks are intentionally kept outside openspec/.openspecui.json so executable project behavior does not pollute persisted UI configuration."

OpenSpec CLI as source of truth

OpenSpecUI defers all workflow state to the OpenSpec CLI: "OpenSpec CLI remains the source of truth for workflow status, instructions, schemas, validation, and archive behavior."

Hook-based document projection

The onReadDocument hook runs server-side to project documents differently for UI consumers without rewriting source files. Example use: appending a glossary to spec display without modifying openspec/specs/:

export const onReadDocument: OnReadDocumentHookV1 = async (ctx, read) => {
  const result = await read()
  if (ctx.document.kind !== 'spec') return result
  const glossary = await readFile(join(ctx.projectDir, 'openspec', 'glossary.md'), 'utf-8')
  return { ...result, markdown: `${result.markdown}\n\n---\n\n${glossary}`, watchFiles: [glossaryPath] }
}

Cross-session handoff

UI configuration persists in .openspecui.json. OpenSpec files persist in openspec/. Between sessions, the state is fully recoverable from these files.

Context compaction

Not applicable for the UI server itself. The Claude Code skills/commands are session-scoped.

07

Orchestration

OpenSpecUI (jixoai) — Orchestration

Multi-agent support

No explicit multi-agent orchestration. The UI server is a single process; Claude Code skills are single-session.

Orchestration pattern

Sequential (artifact pipeline: proposal → design → specs → tasks → implementation → archive).

Prompt chaining pattern

Yes — the openspec-apply-change skill calls openspec instructions apply --change "<name>" --json to get the next instruction dynamically. The CLI output becomes the next prompt stage's input. This is the same prompt-chaining pattern as taskmaster-ai's analyze-complexity → expand-task.

Isolation mechanism

None specified. The UI server operates in-place.

Multi-model support

The ai-provider package suggests multi-provider support (Anthropic, OpenAI, Gemini — from intellij-openspec feature-reference, same ecosystem). The openai-completion-translator package in the monorepo confirms OpenAI API integration. However, the Claude Code skills/commands are single-model (Claude Code).

Execution mode

Interactive-loop (local web server) + one-shot (static export) + interactive-loop (Claude Code skills session).

Subagents

None explicitly. Each OPSX skill is a single-agent operation.

Crash recovery

Hook failures fall back gracefully: "If a hook throws, OpenSpecUI falls back to the default result and attaches diagnostics instead of blocking the UI."

08

Ui Cli Surface

OpenSpecUI (jixoai) — UI & CLI Surface

CLI binary

  • Name: openspecui
  • Entry: packages/cli/ → compiled by tsdown
  • Subcommands: export (at minimum)
  • Flags: [path], --port N, -o <outDir>, --base-path <path>, --clean
  • Is thin wrapper: No — launches its own web server

Local web dashboard

  • Exists: Yes
  • Type: Web dashboard (local HTTP server)
  • Port: 3100 (default)
  • Tech stack: React 19 + TypeScript + Node.js server (packages/web, packages/server)
  • Features:
    • Dashboard: specs/changes/tasks status
    • Config and schema viewers + editors
    • OPSX compose panel (triggers OpenSpec CLI actions from UI)
    • Multi-tab PTY terminal (xterm + ghostty-web)
    • Full-text search (live mode + static mode)
    • Static snapshot export (openspecui export)
    • OpenSpec 1.3 profile/workflow sync (Settings → OpenSpec Profile & Sync)
    • CLI version check/gating (blocks core interactions if CLI version unsupported)

Static export mode

openspecui export -o ./dist
openspecui export -o ./dist --base-path /docs --clean

Produces a static HTML snapshot for hosting on GitHub Pages, Netlify, etc.

Nix support

nix run github:jixoai/openspecui -- --help
nix develop

Claude Code integration

  • 10 slash commands under /opsx:*
  • 10 skills under openspec-*
  • Both commands and skills mirror each other (command = human entry point, skill = autonomous activation)

IDE integration

Not directly — Claude Code skills operate in the Claude Code CLI environment.

Observability

  • CLI version gating: UI shows "OpenSpec CLI Required" and blocks interactions if CLI is outside supported range
  • Hook diagnostics: hook failures attach diagnostic messages to results rather than blocking
  • No structured audit log

OpenSpec 1.3 additions noted

Bob Shell, ForgeCode, Junie, Lingma, refined GitHub Copilot detection, OpenCode .opencode/commands/ directory all supported via profile/workflow sync.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.