Docktree Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• internal/config/config.go
• internal/cli/init.go
• internal/cli/up.go
• internal/cli/render.go
• internal/cli/worktree.go
• skills/docktree/SKILL.md

Docktree is a Go-based CLI tool designed to facilitate the use of Docker Compose across multiple git worktrees. It solves the common problem of resource collisions—specifically project names, host ports, and container names—that occur when running standard Docker Compose stacks in parallel worktrees. By automatically generating override files, Docktree provides each worktree with its own isolated environment, including unique port allocations and container naming conventions.

The system is built to be "agent-native," offering full JSON output support for every command, which allows AI coding agents to drive the CLI for automated end-to-end testing and environment management. It supports both isolated per-worktree services and a repo-scoped shared platform tier for services like databases that might be shared across worktrees.

Sources: README.md:3-13, skills/docktree/SKILL.md:12-16

Core Architecture and Data Flow

Docktree operates by wrapping standard docker compose commands. It intercepts the startup process to perform port discovery, state management, and override generation. The primary state of a worktree environment is managed within a .docktree directory located at the worktree root.

The Up Workflow

When a user executes docktree up, the system follows a specific sequence to ensure isolation:

1. Identity Detection: Determines the repository name, branch, and worktree root to generate a unique InstanceName.
2. Configuration Loading: Loads docktree.yml from the main repository root to ensure consistent settings across worktrees.
3. Port Allocation: Scans for required ports and allocates unique host ports from a defined range (default 41000–49999).
4. Override Generation: Creates a docker-compose.override.yml that applies isolated naming and port mapping.
5. Execution: Invokes docker compose up -d using the original files plus the generated overrides.

Sources: internal/cli/up.go:37-70, internal/cli/up.go:210-245, README.md:32-37

The following diagram illustrates the lifecycle of a service startup through Docktree:

This flow ensures that no two worktrees attempt to bind to the same host port or use the same Docker project name.
Sources: internal/cli/up.go:37-290

Configuration Management

Docktree uses a docktree.yml file to manage environment behavior. While it can work with zero configuration by using defaults, it provides extensive options for customizing how files are synced, how ports are allocated, and which services are shared.

Key Configuration Sections

Section	Purpose	Default / Key Options
compose	Specifies which compose files to use.	files: [docker-compose.yml]
setup	Defines files to copy or symlink into new worktrees.	copy: [.env], symlink: [node_modules]
ports	Controls host port allocation range and bind address.	range: 41000-49999, bind_host: 127.0.0.1
shared	Configures the platform tier for shared services.	tenancy: full_share or per_database
state	Defines the directory for generated files.	directory: .docktree

Sources: internal/config/config.go:102-132, README.md:65-88

Shared Services Tier

Docktree supports a "platform tier" for services shared across all worktrees. This is useful for large databases where running a new container per branch is too resource-intensive. It supports different tenancy models:

• full_share: Every worktree connects to the exact same service and database.
• per_database: The shared service is used, but Docktree provisions a unique logical database (e.g., a specific PostgreSQL schema/database) for each worktree.

Sources: internal/config/config.go:48-61, internal/config/config.go:250-265

CLI Subcommands and Functionality

Docktree provides a suite of native commands that extend Docker Compose functionality with worktree awareness.

Native Command Summary

• init: Scans compose files and generates a docktree.yml proposal. It includes an --apply mode for automated configuration via JSON.
• status: Shows running services, their health, and their allocated URLs. Can show all worktrees using the -a flag.
• clean: Identifies and removes resources (containers, networks, ports) associated with worktrees that no longer exist on disk.
• sync: Propagates changes in setup files (like .env) from the main repository to all active worktrees.
• platform: Manages the lifecycle of the shared services stack (up, down, status, clean).

Sources: internal/cli/help_doc.go:110-170, internal/cli/init.go:70-130, internal/cli/render.go:280-310

Machine-Readable Interface

Every native command supports the --json global flag. When enabled, Docktree writes a single JSON object to stdout containing the result of the operation, while standard Docker progress output is redirected to stderr.

{
  "instance": {
    "project_name": "myrepo-feature-branch",
    "worktree_root": "/path/to/worktree"
  },
  "ports": [
    {
      "service": "web",
      "container_port": 80,
      "host_port": 41002
    }
  ]
}

Sources: skills/docktree/SKILL.md:37-70, internal/cli/render.go:740-755

Resource Isolation and Transformation

Docktree achieves isolation through several transformation strategies applied during the override generation:

1. Project Naming: It forces a unique project name based on a slug of the repository and branch name, preventing Docker Compose from grouping containers from different worktrees together.
2. Container Naming: It typically strips or rewrites container names to avoid "name already in use" errors from the Docker engine.
3. Network Isolation: It generates internal networks for each worktree project, ensuring service-to-service communication remains within the worktree boundaries.
4. Volume Mapping: Named volumes can be isolated (unique per worktree) or shared globally based on the volumes.share configuration.

Sources: internal/cli/up.go:240-270, internal/config/config.go:88-95, internal/cli/worktree.go:200-210

The relationship between configuration and runtime instances ensures that the specific rules defined for the repository are applied consistently to every new worktree environment.
Sources: internal/config/config.go:14-40, internal/cli/up.go:210-230

Conclusion

Docktree serves as a critical infrastructure layer for developers and automated agents working in multi-branch environments. By automating the complexities of Docker Compose resource management and port allocation, it enables seamless parallel development and testing. Its strict adherence to JSON output and isolated state management makes it a robust tool for both human developers and modern AI-driven development workflows.