WorktreeForge

WorktreeForge is the building for managing git worktrees — separate checkouts of the same repository on different branches, so an agent can work on one change while you (or another agent) work on another, without stepping on each other.

At a glance

• Default agents: Worktree agent
• Best for: Parallel-track changes; keeping experimental work off the main checkout; running multiple Developers on the same repo without conflict
• Skills it ships with: /cleanup-worktree, /merge-worktree, /implement-the-prd-in-worktree
• Place from: Building Type Drawer → WorktreeForge

How It Works

A git worktree is a second working copy of the same repository attached to a different branch. It lives in its own directory on disk and lets you have multiple branches checked out at once without stashing or switching. WorktreeForge automates the creation, use, and cleanup of these worktrees so agents can use them comfortably.

When you ask the Worktree agent to generate a worktree, it creates a branch (named for the task), checks it out into a sibling folder, and reports the path back to you. That folder is now a self-contained workspace. You can hand it to a Developer in CodeForge using /implement-the-prd-in-worktree, and the Developer will read and write inside the worktree instead of touching your main checkout.

When the work is done, /merge-worktree takes the branch back to your default branch (or whichever target you pick) and /cleanup-worktree removes the worktree directory and prunes the branch. The point of the building is that you don’t have to remember any of the underlying git worktree add / git worktree remove invocations — the agent runs them and reports.

WorktreeForge requires the project’s folder_path to be a git repository. It runs git commands against that repository.

Default agents

• Worktree agent. The Worktree agent is the operator for git worktrees. Talk to the Worktree agent when you want to spin up an isolated checkout for a piece of work, when you need to merge a worktree back, or when you have stale worktrees you want torn down. The Worktree agent does not write feature code or run reviews — they manage the worktree lifecycle and then hand the worktree path to whichever agent will actually do the work.

Configuration

WorktreeForge is a single-agent building. From its Building Window you can:

• Override the Worktree agent’s prompt — for example, to enforce a branch-naming convention.
• Change the model. Worktree operations are mostly tool calls, so a fast model is usually fine.
• Add additional directories if you want worktrees created outside the default sibling-folder location.

The three skills under At a glance are installed by default:

Skill	What it does
/cleanup-worktree	Removes one or more worktrees, prunes their branches, and confirms the result.
/merge-worktree	Merges a worktree’s branch back into a target branch and reports any conflicts.
/implement-the-prd-in-worktree	Creates a worktree for a PRD and hands its path to a Developer for implementation.

Typical workflow

1. Place WorktreeForge in a project whose folder_path is a git repository.
2. Open the Worktree agent. Describe the change you want to isolate: “Spin up a worktree for the redesign of the settings page.”
3. The agent creates a branch (for example, worktree/redesign-settings), checks it out at a sibling path (for example, ../<project>-redesign-settings/), and reports the path.
4. From the Planner in CodeForge, draft a PRD as usual. When handing off, use /implement-the-prd-in-worktree and point the Developer at the worktree path.
5. The Developer implements the PRD inside the worktree. Your main checkout is untouched. You can keep working in the main tree in parallel.
6. When the change is reviewed and ready, ask the Worktree agent to /merge-worktree. The branch is merged into your target branch.
7. Run /cleanup-worktree to remove the worktree directory and prune the branch.

A common pattern is to run two or three worktrees at once: one for a feature, one for a bugfix, one for an experiment. Each has its own Developer conversation. The Worktree agent tracks the set.

Limitations

• WorktreeForge only manages git worktrees. If your project isn’t a git repository, the building has nothing to do.
• Merging a worktree can produce conflicts. The Worktree agent reports them; resolving them is on you (or a Developer you delegate to).
• Worktrees consume disk space — each one is a full checkout. If you spin up many at once, expect the project folder’s parent directory to grow.
• The Worktree agent does not implement features. It creates the workspace and hands it over. Always pair with a Developer (typically in CodeForge) for the actual code.
• Force-pushing to or rebasing a worktree’s branch from outside Viberia can confuse the agent. If you need to do that, use /cleanup-worktree afterward and start a fresh worktree.

Related

• CodeForge — the engineering building most likely to consume a worktree.
• Workflows: Loops, Councils, PRDs — how PRD handoffs work, including the -in-worktree variant.
• Skills (Slash Commands) — general explanation of how slash commands are invoked.