Workspaces
A workspace is any folder containing an openspec/ directory. Register it once and SpecForge tracks every change inside it — including the ones living in other git worktrees.
Adding a workspace
Open Settings from the gear in the sidebar footer, choose + Add workspace, and pick a folder. The folder must contain an openspec/ directory; anything else is rejected as “not an OpenSpec workspace”.
In a browser there is no native folder dialog to open, so the same section shows a path field instead: type or paste the absolute path and choose + Add. It is validated exactly as the picker’s folder is. That is the route you take after npx @avantmedia/specforge, and also inside the desktop app’s own Web UI tab — see Web UI & remote access.
Workspaces can also be added, removed, renamed and recoloured from the terminal UI’s Settings screen — see Terminal UI. All three surfaces share one registry.
Git-worktree discovery
If a registered workspace is a git repository, SpecForge discovers the repository’s other worktrees automatically. You register the repository once, not each worktree.
In the tree, a repository groups its worktrees together. A change open in several branches expands to one instance per worktree, and each instance carries:
- the branch name it lives on
- a task-progress meter
- a relative “modified” time
[diverged]when that branch’s copy of the change differs from the default branch’s[stale]when the change is already archived on the default branch but is still active here — the signal that this branch can probably be closed. It is about state, not content: a stale copy can be byte-identical to the archived one
Committed, modified, or untracked
Each change instance also carries a working-tree badge answering the question an agent’s “done” does not: has this spec actually landed in git? Committed means the change’s files match the branch; modified and untracked mean there is work sitting in the working tree that no commit holds yet. Repository rows carry a dirty rollup, so an unclean worktree is visible without expanding anything.
The badges are derived from git status runs that never block the UI, and refresh on git activity, spec edits, and whenever the window regains focus.
Names and colours
Each workspace carries a display name you can rename inline, and a tint colour picked from a curated swatch set. The colour marks the workspace’s rows in the tree, so repositories stay tellable apart at a glance; both persist across restarts, along with your expand and collapse state and the window geometry.
Commits are coloured differently — by author — in the commit garden.
Parking a workspace
Every workspace has an enabled toggle in Settings. Disabled, it disappears from the tree and stops counting toward the badge — but it stays registered and watched, and still shows up on the Dashboard. Use it to park a dormant project without losing it.
Browsing the rest of the repository
Clicking a repository’s top-level row opens a read-only file browser over every markdown file in it — not just the OpenSpec artifacts — with a folder tree, a path filter, and the same rendering the spec views use. Files ignored by git stay hidden.
This is the one deliberately pull-based view in the app: rescanning a whole repository on every file event would be wasteful, so the browser carries a Refresh button instead of a watcher.
The archive
Shipped changes stay readable. The archive browser — from the sidebar footer, or by clicking a ship on the Dashboard — lists a workspace’s archived changes newest first with their dates, searchable, each opening into the same artifact reader as an active change. It loads on demand and refreshes live while open.
WSL2 workspaces (Windows)
On Windows, a workspace living inside WSL2 — reached via \\wsl.localhost\<distro>\… — is detected automatically and handled specially: the share reports no filesystem events, so SpecForge falls back to periodic re-scanning (interval configurable in Settings, default 10 seconds), and git commands run through wsl.exe inside the distro rather than against the slow 9P share. Registration, badges and the tree work the same as for a native workspace.
Local and remote state
The registry lives in SpecForge’s own configuration directory, shared by the desktop app and the terminal UI on the same machine — register a workspace in one and the other sees it, a running desktop app on its next launch.
Over SSH that directory belongs to the remote machine, so a remote terminal UI reflects whatever is registered there, independent of your laptop. There is no network sync: register workspaces on the host where you run it.