Worktree Setup

Git worktrees don't include gitignored files like .env, so new worktrees start broken. Codemux fixes this by copying matching files from your main project into each new worktree automatically.

.codemuxinclude

Create a .codemuxinclude file in your project root listing the gitignored files that should be copied into new worktrees. Uses gitignore-style patterns, one per line.

.env
.env.*
config/master.key
.claude/settings.local.json

This file should be committed to git so the whole team shares the same patterns. It runs before setup scripts, so your scripts can depend on .env being present.

Default Patterns

If no .codemuxinclude file exists, Codemux falls back to:

1. Project setting — custom patterns configured in Settings > Projects > Worktree Includes
2. Built-in defaults — .env, .env.*, .env.local

This means .env files are copied automatically even if you haven't configured anything. To customize, either create a .codemuxinclude file (shared with your team) or edit the patterns in Settings (local to your machine).

Docker with Worktrees

Each worktree has a different directory name, so Docker Compose creates separate containers per worktree by default. To share containers across worktrees, pin the project name in your .env:

COMPOSE_PROJECT_NAME=my-project

Add .env to your .codemuxinclude (or rely on the defaults) so every worktree gets this value. Docker Compose reads .env automatically from the working directory.

Re-run Setup

To push updated files or re-run setup scripts on an existing worktree:

Right-click the workspace in the sidebar and select Re-run Setup. This re-copies worktree includes and re-runs all setup commands.

Environment Variables

Setup and teardown scripts have access to these variables:

CODEMUX_PORT assigns a stable, deterministic port range per workspace so dev servers across worktrees don't collide.

Examples

Shared Docker services (Node.js + Postgres)

Multiple agents edit code in parallel, all hitting the same database and services running from the main project.

.env

DATABASE_URL=postgres://localhost:5432/myapp
COMPOSE_PROJECT_NAME=myapp

.codemuxinclude

.env

Run docker compose up once in your main project. Every new worktree gets the same .env, so agents connect to the same running containers.

API keys only (no Docker)

Each worktree gets credentials automatically — agents work independently with no extra setup.

.env

OPENAI_API_KEY=sk-...
STRIPE_SECRET_KEY=sk_test_...

.codemuxinclude

.env

Isolated containers per worktree

Each worktree gets its own Docker stack with a separate database. Useful when agents run conflicting database migrations.

.env

DATABASE_URL=postgres://localhost:5432/myapp

No COMPOSE_PROJECT_NAME — Docker Compose uses the directory name, so each worktree gets its own containers. Use $CODEMUX_PORT in your setup script to avoid port conflicts:

.codemux/config.json

{
  "setup": [
    "sed -i \"s/5432/$CODEMUX_PORT/\" .env",
    "docker compose up -d",
    "npm install"
  ],
  "teardown": ["docker compose down -v"]
}