Coasts

Conductor

Quick setup

Requires the Coast CLI. Copy this prompt into your agent's chat to set up Coasts automatically:

You can also get the skill content from the CLI: coast skills-prompt.

Important: Conductor runs each session in an isolated git worktree. The setup prompt creates files that only exist in the current workspace — commit and merge them into your main branch or they won't be available in new sessions.

After setup, fully close and reopen Conductor for changes to take effect. If the /coasts command does not appear, close and reopen again.

Setup

Add ~/conductor/workspaces/<project-name> to worktree_dir. Unlike Codex (which stores all projects under one flat directory), Conductor nests worktrees under a per-project subdirectory, so the path must include the project name. In the example below, my-app must match the actual folder name under ~/conductor/workspaces/ for your repo.

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

Conductor allows you to configure the workspaces path per-repository, so the default ~/conductor/workspaces may not match your setup. Check your Conductor repository settings to find the actual path and adjust accordingly — the principle is the same regardless of where the directory lives.

If you have more than one Conductor project configured for the same repository, each project creates workspaces under its own subdirectory (e.g. ~/conductor/workspaces/my-app-frontend, ~/conductor/workspaces/my-app-backend). The worktree_dir entry must match the directory name Conductor actually creates, so you may need multiple entries or need to update the path when switching between projects.

Coasts expands ~ at runtime and treats any path starting with ~/ or / as external. See Worktree Directories for details.

After changing worktree_dir, existing instances must be recreated for the bind mount to take effect:

coast rm my-instance
coast build
coast run my-instance

The worktree listing updates immediately (Coasts reads the new Coastfile), but assigning to a Conductor worktree requires the bind mount inside the container.

Where Coasts guidance goes

Treat Conductor as its own harness for working with Coasts:

  • put the short Coast Runtime rules in CLAUDE.md
  • use Conductor Repository Settings scripts for setup or run behavior that is actually Conductor-specific
  • do not assume full Claude Code project command or project skill behavior here
  • if you add a command and it does not appear, fully close and reopen Conductor before testing again
  • if this repo also uses other harnesses, see Multiple Harnesses and Skills for Host Agents for ways to keep the shared /coasts workflow in one place

What Coasts does

  • Run — coast run <name> creates a new Coast instance from the latest build. Use coast run <name> -w <worktree> to create and assign a Conductor worktree in one step. See Run.
  • Bind mount — At container creation, Coasts mounts ~/conductor/workspaces/<project-name> into the container at /host-external-wt/{index}.
  • Discovery — git worktree list --porcelain is repo-scoped, so only worktrees belonging to the current project appear.
  • Naming — Conductor worktrees use named branches, so they appear by branch name in the Coasts UI and CLI (e.g., scroll-to-bottom-btn). A branch can only be checked out in one Conductor workspace at a time.
  • Assign — coast assign remounts /workspace from the external bind mount path.
  • Gitignored sync — Runs on the host filesystem with absolute paths, works without the bind mount.
  • Orphan detection — The git watcher scans external directories recursively, filtering by .git gitdir pointers. If Conductor archives or deletes a workspace, Coasts auto-unassigns the instance.

Example

[coast]
name = "my-app"
compose = "./docker-compose.yml"
worktree_dir = ["~/conductor/workspaces/my-app"]
primary_port = "web"

[ports]
web = 3000
api = 8080

[assign]
default = "none"
[assign.services]
web = "hot"
api = "hot"
  • ~/conductor/workspaces/my-app/ — Conductor (external, bind-mounted; replace my-app with your repo folder name)

Troubleshooting

  • Worktree not found — If Coasts expects a worktree to exist but cannot find it, verify that the Coastfile's worktree_dir includes the correct ~/conductor/workspaces/<project-name> path. The <project-name> segment must match the actual folder name Conductor creates under ~/conductor/workspaces/. See Worktree Directories for syntax and path types.
  • Multiple projects for the same repo — If more than one Conductor project is configured for the same repository, each project creates workspaces under a different subdirectory. The worktree_dir must be updated to match the directory Conductor dynamically creates for the active project. If you switch between projects, the path changes and the Coastfile needs to reflect that.

Conductor Env Vars

  • Avoid relying on Conductor-specific environment variables (e.g., CONDUCTOR_PORT, CONDUCTOR_WORKSPACE_PATH) for runtime configuration inside Coasts. Coasts manages ports, workspace paths, and service discovery independently — use Coastfile [ports] and coast exec instead.