Canopod documentation

Get Canopod running, set up your repository, and give each branch a workspace of its own. Start with a guide below, or search for a setting, command, or problem.

Install CanopodChoose a download for your platform and follow the installation guide. Create your first worktreeGo from a registered repository to a new branch with its own working directory. Connect a coding agent with MCPSet up Claude Code or Codex, choose repository access, and explore the 15 tools. Configure your repositoryDefine the setup steps, service commands, and port rules your project needs.

Start on your own machine#

New to Canopod? What Canopod is explains how worktrees, services, and agents fit together. On a Mac with Apple Silicon, install with Homebrew:

brew install --cask emidhun/canopod/canopod

Follow Install on macOS for the first launch. Windows and Linux packages are also available, but remain experimental and have not been validated on a desktop.

Once installed, add a repository, review the detected services and setup commands, then follow Your first worktree. Canopod runs the commands you configure; what gets installed or provisioned depends on your project.

Connect Claude Code, Codex, or another MCP client#

The optional local MCP server lets an agent inspect worktrees, read service logs, and work with the repositories you allow. MCP is off by default. You choose repository access and grant worktree creation, service control, and configuration changes separately.

MCP and coding agents covers connection steps, permissions, all 15 tools, and headless setup. For a guided introduction, explore Canopod MCP. Read Security for the boundaries around local commands and connected clients.

Find the part you need#

Branches and worktreesCreate, switch between, and clean up worktrees without losing track of each branch. Services and portsConfigure the processes you run and assign ports using each worktree's index. Postgres databasesConfigure database creation, snapshots, and restore workflows for your project. Terminals and agentsOpen a shell or launch an agent with the context of the selected worktree.

For the app itself, start with The main window, Logs, and Keyboard shortcuts. Troubleshooting connects common symptoms to checks and fixes.

Adapt an example to your project#

Use a worked configuration for a simple web app, a Node + Postgres app, the ToolJet monorepo, or Rails, Django, Go, and Rust. Template variables explains how paths, branch names, and port values are passed into your commands.

Working on Canopod itself? See Building from source, Building a release, and the command and event reference.

About these guides#

These guides describe Canopod 0.5.0. Limitations records platform support, unfinished controls, and known boundaries. Controls marked coming soon are visible in the app but are not implemented yet.

NextWhat Canopod is