Skip to content
Fredrin
Documentation

Working the board

Branches and worktrees

One ticket, one branch, one worktree. Not a metaphor and not a sandbox: a real git worktree you can cd into.

Why worktrees

A git worktree is a second working directory attached to the same repository. Same history, same objects, different checked-out branch, different files on disk.

That is exactly the primitive parallel agents need. Ten Workers in ten worktrees are ten independent checkouts that cannot overwrite each other, all sharing one .git. No cloning the repo ten times, no stashing, no branch switching under a running process.

If you want the mechanism in depth, including how to run it by hand, we wrote a complete guide to git worktrees.

What Fredrin does

When a ticket runs, Fredrin creates the branch, creates a worktree for it next to your repository, and starts the Worker inside it.

The Worker's whole world is that directory. It reads your project context from there, edits files there, commits there, and pushes from there.

The target branch

A ticket's pull request targets your default branch unless something says otherwise. The main exception is a goal with a staging branch, where the goal's tickets target the staging branch and the staging branch merges to default at the end.

Checking out a ticket

Any ticket's branch is one click from your editor. Fredrin can open the worktree directly, so reviewing a change locally does not mean stashing whatever you were doing.

This is worth internalising: you never need to switch branches to look at a ticket. Your own working directory stays exactly as you left it.

Cleanup

A completed ticket's worktree is removed. The branch's fate follows your repository's own settings on GitHub, so if you delete branches on merge, Fredrin's branches are deleted on merge.

If you are working inside a Fredrin repo yourself

One rule, and it is not obvious: never run git stash in a worktree.

The stash stack is repository-global, not per-worktree. Every worktree shares one .git, so a stash pushes onto the same stack every other running Worker uses, and a bare git stash pop pops whatever is on top, which is very often somebody else's work.

To compare against another state without mutating your working tree, use a throwaway worktree, read the file with git show, or just commit first. A commit is cheap, local, and amendable.

Next steps