SpecForge

Terminal UI

The change browser, dashboard and commit garden in a single binary you can run over SSH, drop into a tmux status line, or keep open beside your editor.

Install

Every release ships the terminal UI as a standalone archive — macOS universal, Linux x64, and Windows x64. Extract it and run ./specforge-tui.

macOS: clear the quarantine flag first. A terminal binary has no Gatekeeper “right-click ▸ Open” dialog, so the desktop workaround does not apply here. Run:

xattr -dr com.apple.quarantine specforge-tui

Three ways to run it

  • Interactive — the full TUI. Browse, dashboard, garden, history, settings.
  • --status — prints every workspace and its active changes, then exits. For piping, scripts, or a quick glance.
  • --line — prints SpecForge · N workspaces · M open changes, then exits. Built for a prompt segment or a tmux status bar.
# tmux status-right
set -g status-right '#(specforge-tui --line)'

# zsh prompt
precmd() { specforge-tui --line }

Keys

  • 1–5 — Browse, Dashboard, Garden, History, Settings
  • j / k (or ↓ / ↑) — move and scroll
  • Tab — switch between the tree and the detail pane
  • Enter / l — open the selected change; h goes back to the tree
  • [ / ] — previous and next artifact tab
  • / — filter the tree by title or name
  • ? — help overlay; q or Ctrl-c quits

The screens

Browse is the workspace and change tree with status glyphs and a task-progress bar, beside a markdown detail pane with an artifact tab bar. Below about 90 columns it collapses to a single focused pane. Dashboard is the progress overview — today’s counts, streak, heatmap and ships — rendered for a TTY. Garden draws today’s commits per repository, coloured per author. History draws the commit-graph rail with box-drawing characters. Settings toggles the app settings and manages the workspace registry — a adds, x removes, r renames, c recolours.

Changes made on the Settings screen persist immediately and appear at once in the running TUI; a running desktop app picks them up on its next launch.

Terminal capabilities

Colour and glyphs are detected once and degrade cleanly. truecolor is used when COLORTERM advertises it, then 256-colour, then the 16 ANSI names; NO_COLOR or TERM=dumb drops colour entirely and the layout still reads through bold and box-drawing. Unicode markers are used only when the locale advertises UTF-8, and fall back to ASCII otherwise.

What it writes

The terminal UI is read-only with respect to your workspaces — it never writes into one. It does write SpecForge’s own configuration when you flip a toggle or add, remove, rename or recolour a workspace: the shared settings file, the workspace registry, and the presentation store, all of which live outside any workspace.