Worktree development #

Use the w commands to run multiple branches in one Coder workspace. Each worktree gets its own application services, ports, and isolated data within shared infrastructure servers.

First setup #

From the Bonsai checkout in your Coder terminal:

mise trust
dockre compose down -v
mise winstall
mise wdev

• winstall installs the worktree tooling, including CodeRabbit’s gtr.
• wdev prepares development dependencies and configuration, provisions the worktree’s data, starts its services, and brings up the dashboard.
• You do not need to run mise dev first. Coder URLs are detected automatically.
• Development secrets come from Doppler. If authentication fails, run mise doppler-login and retry. mise wdev --env-file /path/to/.env can use an existing development environment file instead.
• The first startup includes image builds and code generation and can take several minutes.

Dashboard #

Open the dashboard through Coder on port 9003. Port 9000 also redirects its landing page there. Run mise wdashboard to start the dashboard without starting a worktree’s application stack.

The dashboard lets you:

• Create worktrees, choosing the branch and base branch. The base defaults to main; creation does not start the services.
• Start and stop worktrees, and copy their paths and ports.
• Open App, Console, editors, database tools, and other development services.
• Start optional tools and restart shared database/Docker UIs.
• Select the worktree that receives callbacks and webhooks.

Active worktrees include newly created ones and those started within the last five days. Active does not necessarily mean running. Active entries are ordered by creation time, newest first; inactive entries use the most recent manager activity, such as starting or stopping.

Create and use a worktree #

mise wcreate my-feature
# Or choose a different base:
mise wcreate another-feature --from existing-branch

The command prints the full cd command for the created directory. Change into that directory and run mise wdev when ready to start it. Worktree commands act on the checkout you run them from.

Optional tool names are docs, swagger, e2e, nigari, storybook, and mcp. App and Console start with wdev. Console runs in Vite development mode and proxies API requests directly to its worktree’s backend.

URLs, callbacks, and port sharing #

Each running worktree reserves a port slot. For example, slot 1 uses 19000 for App and 13050 for Console. Prefer the dashboard links rather than constructing URLs yourself: ports can change when a stopped worktree restarts. Browser-facing worktree apps use Coder HTTPS URLs.

Only one worktree receives callbacks and webhooks through the fixed entry point:

mise wtakeover

Run this from the intended worktree before testing an integration callback. Opening another worktree’s App link does not change the callback selection. The dashboard’s Webhooks action controls the same selection.

If Coder login is missing or expired, services can still run, but automatic port sharing may fail and browser requests may encounter an extra login. Run:

mise wpublic

This handles Coder login and republishes the configured ports for all running worktrees, not just the current one. The dashboard also provides a Coder login flow. Shared internal tools retain their configured sharing level.

Database migrations #

Run these from the worktree whose schema you want to change:

mise wdb-migrate-apply
mise wdb-migrate-apply-non-linear
mise wdb-migrate-down       # Revert one migration
mise wdb-migrate-down 2     # Revert two migrations

These use the current checkout’s migration files and registered worktree database. Infrastructure must be running. Down retains Atlas’s confirmation. Use non-linear application when out-of-order migrations require it, rather than as the default. Schema authoring still follows the normal migration workflow.

Shared infrastructure #

Yugabyte, AIOps PostgreSQL, Redis, RabbitMQ, LocalStack, ClamAV, and OpenTelemetry are shared servers. Worktrees use separate logical databases, Redis claims, RabbitMQ virtual hosts, and S3 buckets. Stopping a worktree releases its Redis claim; do not treat Redis as persistent storage across stops.

Shared configuration lives in <git-common-dir>/worktree-dev/infra.json. Each checkout has its own .worktree-dev/compose.json for application services.

When changing shared infrastructure, bump INFRA_VERSION in tools/worktree-dev/infra.ts. Startup regenerates older configurations and rejects downgrades. A different configuration with the same version is a conflict, including when two branches independently bumped the version. Resolve the definitions and bump the version, or explicitly rebuild:

mise wdev --rebuild-infra

This affects every worktree using the shared infrastructure. It recreates shared containers and removes obsolete containers, but preserves named data volumes.

Troubleshooting #

• Need startup details: use mise wlogs and mise wcompose ps from the affected worktree.
• Missing shared TypeScript declarations: run mise ts-lib-build. A stale webapp incremental typecheck cache may also need clearing after rebuilding.
• High Rust build CPU usage: WDEV_BUILD_JOBS=2 mise wdev limits Cargo build jobs per worktree. This is not a strict two-core CPU limit.
• Returning to ordinary mise dev: stop worktree services as needed with mise wdown, then run mise wdashboard-down to release port 9000. The regular dev scripts and worktree startup are separate.

Worktree task definitions live in tools/worktree-dev/.tasks.toml. The scripts are in tools/worktree-dev; the React dashboard and tRPC backend are in tools/worktree-dashboard.

Run mise worktree-dashboard-check and mise worktree-dev-check for formatting, lint, and TypeScript checks. These also run through mise ts-check in CI. Use mise worktree-dashboard-format-fix or mise worktree-dev-format-fix to apply formatting. Internal dashboard text does not require i18n.