runnable-worktrees

Runnable worktrees

When configured, each builder worktree (.builders/<id>/) becomes runnable: reviewers can run whatever your dev command starts — a dev server, cargo run, expo start, a test watcher, a build script — against the builder's branch without cd'ing, installing, or hunting for the command. Opt-in via .codev/config.json; unconfigured repos see zero behavior change.

Config: the worktree block

{
  "worktree": {
    "symlinks":   ["..."],   // globs symlinked from the workspace root into each new worktree
    "postSpawn":  ["..."],   // shell commands run inside each new worktree after createWorktree
    "devCommand": "..."      // consumed by `afx dev <builder-id|main>`
  }
}

• symlinks — globs resolve from the workspace root and link into the worktree at the same relative path. Root .env and .codev/config.json are always symlinked regardless. Symlinks, not copies, so edits to main's env files reflect instantly in a running dev session. A directory match is silently skipped (a glob cannot mask the worktree's own source) unless the entry ends in a slash: ".local-user-data/" is treated as a literal path and links the directory whole — shared with the parent, not branch-isolated. A dangling link is fine if the source does not exist yet.
• postSpawn — commands run sequentially with cwd = worktree path. A non-zero exit aborts the spawn loudly; the half-built worktree stays for inspection.
• devCommand — the foreground command that starts your dev process. Required for afx dev.

Codev does not auto-detect your stack. Pick a recipe below.

CLI

afx dev <builder-id>     # start dev in that builder's worktree
afx dev main             # start dev in the MAIN workspace (Codev-managed)
afx dev --stop           # stop the running dev PTY (builder or main)
afx setup <builder-id>   # re-apply symlinks + postSpawn to an existing worktree (idempotent)

One dev PTY at a time, across {main + all builders} — deliberate; see URLs are load-bearing. main is a reserved target running worktree.devCommand in the main checkout as a Codev-managed, swappable PTY, symmetric with builders. Starting a second target prompts to swap; a same-target request prints the existing terminal URL and exits. Dev PTYs are non-persistent — a Tower restart or crash kills them; re-run to restart.