Settings

Settings lives behind the gear in the sidebar footer. The sections below follow that view top to bottom. The terminal UI has a Settings screen of its own, but a much smaller one — the two quota gauges, an Appearance colour scheme, and the workspace list.

Workspaces

Add, remove, rename and recolour workspaces — see Workspaces for what registration means. Each workspace also carries an enabled toggle: a disabled workspace disappears from the tree and stops counting toward the badge, but stays registered and watched, and still appears on the Dashboard. Park a dormant project without unregistering it.

Identity

The Dashboard’s personal numbers — streak, heatmap, today’s counts — attribute work to you, resolved automatically from your git configuration, with a manual entry when there is nothing to resolve. If your commits span several emails or names, add them as aliases so they fold into one developer instead of splitting your history.

This is the only attribution SpecForge stores. Everyone else — teammates, or agents committing under their own identity — is shown by the git author recorded on the commit, with no naming or merging step of your own.

Desktop notifications

Notifications fire when a change first appears and when it is archived — never on ordinary file edits. Editing a proposal all afternoon produces nothing; finishing one produces exactly one notification.

On macOS the Dock badge mirrors the tray count, so the number is visible in the Dock and the ⌘-Tab switcher as well as the menu bar.

Usage-quota gauges

SpecForge can show a small gauge for your AI coding-assistant usage — in the desktop sidebar footer, and in the terminal UI’s title bar. There are two, independent of one another:

Claude — your 5-hour and weekly usage, with the 5-hour window split into five one-hour segments and the weekly into seven day-long segments. When Anthropic reports separate weekly limits for specific models, the gauge grows one extra weekly bar per model, labelled with the model’s name.
ChatGPT — the same gauge for your ChatGPT plan. Its segment count and length come from whatever window length the usage endpoint reports, falling back to 5 hours and 7 days only when the response omits it.

Both colour green → orange at 70% → red at 90%, and show a reset countdown when a window is spent. Each bar carries a live “now” marker at the elapsed point, so you read pace at a glance — budget spent, the fill, against time elapsed, the marker — rather than a per-hour history.

Both are off by default, and independent.

Enabling the Claude gauge reads your local Claude Code login to query Anthropic’s usage endpoint. Enabling the ChatGPT gauge reads your local Codex CLI login to query ChatGPT’s. Both logins are read, never modified, and these are the application’s only network calls. With both toggles off, SpecForge makes none at all — nothing is read, and nothing is sent.

On a narrow terminal the title bar drops whole trailing gauge groups, ChatGPT before Claude, so enabling ChatGPT can never hide an otherwise-visible Claude gauge.

Startup

Launch at login registers SpecForge with the operating system’s own login-items mechanism — it is stored in the OS, not in SpecForge’s settings file, and queried fresh each time the settings view opens, so what you see is what the OS will actually do.

Web UI

Serve the same UI to a browser at http://127.0.0.1:<port>, with optional Tailscale Serve support for reaching it from your other machines. The trust model deserves its own page: Web UI & remote access.

WSL workspaces (Windows)

On Windows, workspaces living inside WSL2 are watched by periodic re-scan rather than filesystem events, because the \\wsl.localhost share reports none. This section sets the scan interval — default 10 seconds. It appears only on Windows; see Workspaces ▸ WSL2.

Appearance (terminal UI only)

The terminal UI’s Settings screen carries one control the desktop app has no equivalent for: a colour scheme, cycled on the Appearance row. It is the only setting that does not go into the shared configuration — each frontend owns its own presentation, so the choice is written to the terminal UI’s own tui.json, beside the other files rather than inside them. See Terminal UI.

What settings write

Toggling a setting, or adding, removing, renaming or recolouring a workspace, writes SpecForge’s own configuration — the shared settings file, the workspace registry, and the presentation store. All three live outside any workspace, in the same configuration directory — as does the terminal UI’s tui.json. The one setting stored somewhere else entirely is launch-at-login, which lives in the operating system as described above.

Nothing here writes into a project. SpecForge does not edit specs, toggle task checkboxes, or touch git, whatever the settings say.