Coasts

Worktree Directories

The worktree_dir field in [coast] controls where git worktrees live. Coast uses git worktrees to give each instance its own copy of the codebase on a different branch, without duplicating the full repo.

Syntax

worktree_dir accepts a single string or an array of strings:

# Single directory (default)
worktree_dir = ".worktrees"

# Multiple directories
worktree_dir = [".worktrees", ".claude/worktrees", "~/.codex/worktrees"]

When omitted, defaults to ".worktrees".

Path types

Relative paths

Paths that don't start with ~/ or / are resolved relative to the project root. These are the most common and require no special handling — they're inside the project directory and automatically available inside the Coast container via the standard /host-project bind mount.

worktree_dir = ".worktrees"
worktree_dir = [".worktrees", ".claude/worktrees"]

Tilde paths (external)

Paths starting with ~/ are expanded to the user's home directory and treated as external worktree directories. Coast adds a separate bind mount so the container can access them.

worktree_dir = ["~/.codex/worktrees", ".worktrees"]

This is how you integrate with tools that create worktrees outside your project root, such as OpenAI Codex (which always creates worktrees at $CODEX_HOME/worktrees).

Absolute paths (external)

Paths starting with / are also treated as external and get their own bind mount.

worktree_dir = ["/shared/worktrees", ".worktrees"]

Glob patterns (external)

External paths can contain glob metacharacters (*, ?, [...]).

worktree_dir = [".worktrees", "~/.shep/repos/*/wt"]

This is useful when a tool generates worktrees under a path component that varies per project (like a hash). The * matches any single directory name, so ~/.shep/repos/*/wt matches ~/.shep/repos/a21f0cda9ab9d456/wt and any other hash directory that contains a wt subdirectory.

Supported glob syntax:

  • * — matches any sequence of characters within a single path component
  • ? — matches any single character
  • [abc] — matches any character in the set
  • [!abc] — matches any character not in the set

Coast mounts the glob root — the directory prefix before the first wildcard component — rather than each individual match. For ~/.shep/repos/*/wt, the glob root is ~/.shep/repos/. This means new directories that appear after container creation (e.g., a new hash directory created by Shep) are automatically accessible inside the container without recreation. Dynamic assigns to worktrees under new glob matches work immediately.

Adding a new glob pattern to the Coastfile still requires coast run to create the bind mount. But once the pattern exists, new directories matching it are picked up automatically.

How external directories work

When Coast encounters an external worktree directory (tilde or absolute path), three things happen:

  1. Container bind mount — At container creation time (coast run), the resolved host path is bind-mounted into the container at /host-external-wt/{index}, where {index} is the position in the worktree_dir array. This makes the external files accessible inside the container.

  2. Project filtering — External directories may contain worktrees for multiple projects. Coast uses git worktree list --porcelain (which is inherently scoped to the current repository) to discover only the worktrees that belong to this project. The git watcher also verifies ownership by reading each worktree's .git file and checking that its gitdir: pointer resolves back to the current repo.

  3. Workspace remount — When you coast assign to an external worktree, Coast remounts /workspace from the external bind mount path instead of the usual /host-project/{dir}/{name}.

Naming of external worktrees

External worktrees with a branch checked out appear by their branch name, the same as local worktrees.

External worktrees on a detached HEAD (common with Codex) appear using their relative path within the external directory. For example, a Codex worktree at ~/.codex/worktrees/a0db/coastguard-platform appears as a0db/coastguard-platform in the UI and CLI.

default_worktree_dir

Controls which directory is used when Coast creates a new worktree (e.g., when you assign a branch that doesn't have an existing worktree). Defaults to the first entry in worktree_dir.

[coast]
name = "my-app"
worktree_dir = [".worktrees", "~/.codex/worktrees"]
default_worktree_dir = ".worktrees"

External directories are never used for creating new worktrees — Coast always creates worktrees in a local (relative) directory. The default_worktree_dir field is only needed when you want to override the default (first entry).

Examples

Codex integration

OpenAI Codex creates worktrees at ~/.codex/worktrees/{hash}/{project-name}. To make these visible and assignable in Coast:

[coast]
name = "my-app"
worktree_dir = [".worktrees", "~/.codex/worktrees"]

After adding this, Codex's worktrees show up in the checkout modal and coast ls output. You can assign a Coast instance to a Codex worktree to run its code in a full development environment.

Note: the container must be recreated (coast run) after adding an external directory for the bind mount to take effect. Restarting an existing instance is not sufficient.

Claude Code integration

Claude Code creates worktrees inside the project at .claude/worktrees/. Since this is a relative path (inside the project root), it works like any other local worktree directory — no external mount needed:

[coast]
name = "my-app"
worktree_dir = [".worktrees", ".claude/worktrees"]

Shep integration

Shep creates worktrees at ~/.shep/repos/{hash}/wt/{branch-slug} where the hash is per-repo. Use a glob pattern to match the hash directory:

[coast]
name = "my-app"
worktree_dir = [".worktrees", "~/.shep/repos/*/wt"]

All harnesses together

[coast]
name = "my-app"
worktree_dir = [".worktrees", ".claude/worktrees", "~/.codex/worktrees", "~/.shep/repos/*/wt"]

Live Coastfile reading

Changes to worktree_dir in your Coastfile take effect immediately for worktree listing (the API and git watcher read the live Coastfile from disk, not just the cached build artifact). However, external bind mounts are only created at container creation time, so you need to recreate the instance for a newly added external directory to be mountable.