Integrations

How to integrate Docktree with your AI agents, development environments, and git worktree managers.

AI Agents & Coding Environments

Docktree is designed to be agent-native. It helps coding agents (such as Claude Code, Codex, Cursor, or OpenCode) spin up and manage development stacks independently without user intervention or manual setup.

1. Installing Agent Skills

Docktree publishes pre-packaged skills that teach agents how to drive the CLI correctly (such as handling lifecycle states and error codes). Install these skills in your workspace:

npx skills add Bnjoroge1/Docktree

2. Programmatic Execution (`--json`)

When scripting agent tools or automated workflows, prefix your commands with the global --json flag. This instructs Docktree to emit structured, machine-readable JSON output on stdout and format errors as JSON objects, bypassing human-readable TUI rendering:

# Programmatically check active worktree port allocations
docktree --json ports --all

# Programmatically start a worktree and parse metadata
docktree --json up

Git Worktree Managers & CLI Tooling

If you use Git worktree helper tools or custom scripts to manage your branches, Docktree can hook directly into your branch creation lifecycle.

One-Command Worktree & Stack Provisioning

Instead of manually running git worktree add, copying environment files, running install scripts, and launching docker compose, you can delegate the entire flow to Docktree:

docktree up --create feature/login --sync

This single command tells Docktree to:

1. Create a git worktree at the configured root (e.g. ../myrepo.worktrees/feature-login).
2. Sync and prepare the workspace using the steps defined in docktree.yml (copying .env files, symlinking node_modules, and running dependency installations).
3. Allocate unique ports and start the container stack in detached mode.

Complementary Integration with Worktree Orchestrators (Worktrunk, Conductor, Orca)

If you or your team uses dedicated git worktree managers or parallel workspace orchestrators like Worktrunk (wt), Conductor, or Orca to run parallel AI agents (like Claude Code or Codex) or manage developer checkouts:

Docktree is 100% complementary. While orchestrators automate the Git worktree creation and workspace-switching lifecycle, Docktree automates the local Docker container isolation and port routing lifecycle. They work hand-in-hand:

• Worktree Orchestrator: Spawns the worktree, switches directories, and handles agent dispatch.
• Docktree: Runs inside the orchestrator's setup/checkout hooks to automatically spin up a collision-free container stack.

Worktrunk (wt.toml) Example

If you use Worktrunk (wt), you can define a post-create hook in your wt.toml configuration to boot the Docktree stack automatically whenever a new worktree is created:

[hooks]
post-create = "docktree up --sync"

With this hook, running wt switch --create feature-a will check out the branch, copy your ignored files, symlink dependencies, allocate ports, and start your Docker containers in one seamless step. You can add the same setup command (docktree up --sync) to Conductor or Orca workspace hooks to have them automatically spin up isolated container stacks for new workspaces.

CI/CD Pipelines (GitHub Actions, GitLab, Jenkins)

Running Docker Compose in parallel CI environments often leads to port and volume conflicts. You can integrate Docktree into your CI workflow to run test suites concurrently on a single runner machine.

For persistent, self-hosted CI runners where multiple jobs execute concurrently on the same host machine, Docktree automatically prevents port and container collisions. Since all jobs run under the same host user, they share a machine-wide port registry (stored in ~/.config/docktree/ports.json) and dynamically allocate free ports on the fly, allowing parallel test runs to execute in complete isolation without interference.

GitHub Actions Example

Save the following step configuration in your test workflow to run parallel Docker containers cleanly:

- name: Install Docktree
  run: curl -fsSL https://docktree.dev/install.sh | sh

- name: Start isolated container stack
  run: docktree up --sync --validate

- name: Run test suite
  run: npm run test:e2e

- name: Teardown and cleanup
  if: always()
  run: docktree down -v

Using the -v flag on teardown ensures that all dynamically created Docker volumes and databases are completely pruned, preventing disk bloat on the runner machine.