Worktrees

A worktree is a second (or third, or tenth) checkout of a repo, each on its own branch, sharing one .git. CodeSense gives every story its own, so agents working on different stories never step on each other’s files, and named agents prepare their declared startup context before they start.

From a story to a worktree

When you open a story’s worktree (Open story workspace on its right-click menu in the left nav), CodeSense:

1. Finds the story’s repo from its source_repo field.
2. Works out the branch: the story’s branch field if set, otherwise the repo’s branch prefix plus the story id (feat/LL-214).
3. Runs git worktree add for that branch, starting from the repo’s start point (main unless you set one).
4. Registers the worktree, then opens its terminal.
5. Runs the repo’s setup commands in the background.

If the worktree already exists, CodeSense reopens it and preserves its files. Opening or focusing a story worktree does not copy or publish context. Named-agent launches wait for registration and setup, then prepare only their declared startup inputs; a failure blocks the launch. Request additional context or publish edits explicitly.

Configure worktrees per repo

Each repo can have its own worktree settings in ~/.codesense/users/<id>/orgs/<org>/_codesense/worktree/<owner>/<repo>.yaml. For ledgerline/api:

version: 1
branch_prefix: feat/
default_start_point: main
worktree_dir: ../{repo}-wt/{slug}
timeout_seconds: 600
setup:
  - npm ci
  - npm run db:migrate
cleanup:
  - docker compose down
env:
  DATABASE_URL: postgres://localhost/ledgerline_dev

Key	What it does	Default
setup	Commands run in a new worktree, in order.	none
cleanup	Commands run before a worktree is removed.	none
env	Extra environment variables for the setup and cleanup commands.	none
branch_prefix	Prefix for branches made from story ids.	feat/
default_start_point	The ref new branches start from.	main
worktree_dir	Where worktrees go, relative to the clone. Only {repo} and {slug} are allowed; {slug} is the branch with / turned into -.	../{repo}-wt/{slug}
timeout_seconds	How long a setup command may run.	600

Setup commands run in the new worktree through a shell, with your login shell’s PATH, so npm, cargo and your scripts are found even when the app was started from Finder. They also get CODESENSE_SOURCE_ROOT, the path of the checkout the worktree was made from, which is handy for copying a local .env:

setup:
  - cp "$CODESENSE_SOURCE_ROOT/.env" .env

Setup runs with a checklist you can watch and cancel. An agent can also read and write this file for you through CodeSense’s MCP tools.

After a worktree exists

An agent can list the worktrees CodeSense manages with list_worktrees, and clean one up yourself with git worktree remove. Context doesn’t sync into an open worktree on its own: an agent there brings in newer context with hydrate_worktree, and sends edits back with reverse sync (see Reverse sync, in Beta).

Clean-up

A worktree is removed only when you remove it. CodeSense never limits how many worktrees you have, and never removes one because it is idle or because its pull request merged.

Removal never publishes context. Normal removal preserves dirty files and refuses ignored files whose safety cannot be proved. Review or explicitly publish the files you need, then remove the worktree.

Worktrees are real git worktrees

CodeSense creates them with git worktree, so git worktree list in the repo shows them, and your editor, scripts and tools treat them like any checkout. Creating one is a normal checkout, not an instant copy: large repos take as long as git worktree add does.