Local Checkouts and Worktrees

Local checkouts and worktrees

Claude needs a working copy of the repo to read, build, test and change code. Fast Lane gives every session its own, and never runs Claude in a checkout you work in.

Finding your checkouts

Fast Lane looks for clones you already have in your code folders. By default those are ~/Code, ~/code, ~/src, ~/Projects, ~/Developer, ~/dev and ~/repos, whichever exist. Change them on the Settings tab (Code folders) or with code_dirs in config.json; an empty list means always clone.

It searches up to three levels deep, skipping hidden folders and things like node_modules, and reads each checkout's .git/config to see which GitHub repos its remotes point at. SSH (git@github.com:owner/repo.git), HTTPS and ssh:// URLs all work, and the folder name doesn't matter. When several checkouts match a repo, a remote named origin beats upstream, then a folder named after the repo wins, then the shorter path.

The scan takes milliseconds and runs at startup, on R, and when you change the code folders. Repos with a checkout show local on the Repos tab. To use a different checkout for one repo, set it with e on the Repos tab, or local_path in the repo's config.

Worktrees

For a repo with a local checkout, each session gets a git worktree of it at <workspace>/.worktrees/<owner>/<repo>/session-<n>:

1. Fast Lane runs git fetch for the matching remote in your checkout.
2. It adds a worktree there, detached at the remote's default branch.
3. Claude works in the worktree.

Only fetch and worktree add ever run in your checkout, so your working tree, current branch and uncommitted changes are never touched. Worktrees share your checkout's objects and branches, so nothing is downloaded again, and a branch Claude commits to is a branch in your repo, ready for you to look at.

Because every session has its own folder, sessions on the same repo can run at the same time (up to max_concurrent overall).

Branch clashes. Git won't check out one branch in two worktrees. If Claude needs a PR's branch while you have it checked out, it checks it out under another name (gh pr checkout N --branch fast-lane/pr-N) and pushes with git push <remote> HEAD:<branch>. Its instructions tell it how.

Cleaning up

• A finished session keeps its worktree for a week, so a reply continues exactly where it left off.
• After a week without activity, the worktree is removed when Fast Lane starts. The session stays; replying to it creates the worktree again at the same path.
• D on the Sessions tab deletes a finished session and its worktree right away.

Removing a worktree throws away uncommitted changes in it. Committed work stays on its branch in your checkout.

Repos without a checkout

They're cloned once into <workspace>/<owner>/<repo> with gh repo clone, and fetched before each new session. Sessions on the same clone run one at a time because they share it.

The workspace defaults to ~/.local/share/fast-lane/workspaces (or under $XDG_DATA_HOME). Change it on the Settings tab.