Register a project once. In Projects → Add Project, pick a folder. Warpforge keeps a local registry and reads or creates .warpforge/workspace.yaml — optionally prefilled from a package.json dev script or a Docker Compose file, or generated interactively by an agent in the bootstrap wizard. Existing .warpforge.yaml, .wf.yaml, and .workspace.yaml files remain supported. Removing a project only unregisters it; the directory and its config stay untouched.
A project opens into tabs, the same way a task does: Backlog, Files, Runtime, and Terminal. Files browses the project’s own checkout without starting a task — pick anything in the tree and it opens in a syntax-highlighted preview, with several files open at once across a tab strip. Each project remembers the tab you left it on, and its name, path, and port range stay pinned above them all.
Bring the real runtime online. Services start in dependency order with captured logs, interpolated environment variables, and readiness detection. Kubernetes port-forwards run alongside local processes and are watched and retried with backoff when they drop. Runtime shows services and port-forwards in one place with their live logs and the http://localhost:… address of anything that is up; start, restart, and stop appear on a row when you point at it, and starting or stopping everything at once is a single click in the section heading. Each project also has interactive terminals inside the app, so a quick git log or one-off script does not need another window.
Search without leaving the task. Press ⌘⇧F for Find in Files: every matching line grouped by file, with a live peek at the surrounding code, and Enter opens the file at that line with the cursor already there. The quick-open palette (double ⇧ or ⌘P) finds text too. Searches stay on files that belong to the project — build output and dependencies don’t bury the results.
Work survives the window. A local Rust daemon owns projects, services, sessions, and task state behind a WebSocket API; the Tauri app is a thin client. Close or restart it and long-running work continues. Task history and agent configuration persist in ~/.warpforge/warpforge.db, the project registry in ~/.warpforge/projects.json.
Review, commit, ship. Browse changed files, read unified or split diffs, accept or reject individual hunks, edit files inline, draft a commit message, commit or amend, update the branch, and push with --force-with-lease — all through git directly. Open pull request additionally needs the GitHub CLI (gh) installed and authenticated; see Install → Requirements.
No port roulette
Every registered project gets a predictable 100-port range beginning at 4000. That is not a registry detail — it is what makes parallel work practical: multiple projects, and multiple agent-built previews inside them, stay online together without fighting over 3000, 5173, or other common defaults.
For services with a configured port, Warpforge selects an available value in the project’s range, sets PORT, and expands references such as ${app.port} in environment variables. The resolved URLs become part of the live context handed to new agent sessions. You can switch projects and come back without stopping unrelated services, rewriting configuration, or chasing address already in use.
Agents see the runtime too
The same services, logs, and controls are available to agents as tools — list_runtime to discover what’s up and on which port, read_service_logs to watch a restart, service_restart to bring something back. An agent that can read the failure it caused fixes it before handing you a diff.
See the configuration reference for the full .warpforge/workspace.yaml schema, and Tasks and backlog for where the work comes from.