cowtree

A separate workspace for every AI agent, at no disk cost

Running several AI coding agents on one project? They overwrite each other's files, or each needs a full copy of your code. cowtree gives every agent its own instant copy that uses almost no disk. Works with Claude Code, Codex and Cursor. Free, open source.

Under the hood: git worktrees built from copy-on-write clones (APFS clonefile), node_modules and build directories included.

brew install paakofiaidoo/tap/cowtree
curl -fsSL https://raw.githubusercontent.com/paakofiaidoo/cowtree/main/install.sh | bash

Version 0.5.0, MIT licensed. Runs on macOS (APFS) and on Linux with btrfs, XFS or bcachefs. Release notes.

cowtree - A separate workspace for every AI agent, at no disk cost | Product Hunt
$ du -sh myapp
311M    myapp
$ cowtree add ~/code/myapp payments-retry
Preparing worktree (new branch 'payments-retry')
~/code/wt/myapp-payments-retry
$ cowtree add ~/code/myapp search-index
~/code/wt/myapp-search-index
$ cowtree add ~/code/myapp fix-login
~/code/wt/myapp-fix-login
$ cowtree ls ~/code/myapp
~/code/myapp  (base)
~/code/wt/myapp-fix-login       [fix-login]       logical 301.0MB  owned 8.0KB
~/code/wt/myapp-payments-retry  [payments-retry]  logical 301.0MB  owned 12.0KB
~/code/wt/myapp-search-index    [search-index]    logical 301.0MB  owned 8.0KB
Captured on a Next.js checkout with its dependencies installed. Free space on the volume, measured with df before and after the three adds: unchanged.

Parallel sessions need parallel checkouts

An AI coding agent that works on a branch needs a working tree of its own; two agents in one checkout overwrite each other. git worktree add solves that, but every worktree is a full second copy of every checked-out file, and node_modules, build/ and .venv are missing until you reinstall them.

On a laptop that is the ceiling on how many sessions you can run. cowtree removes it: the base checkout stays on main, every session gets a worktree on its own branch, and each one owns only the bytes it writes.

704 MBcheckout with dependencies
3.5 MBthe same checkout as a cowtree worktree
1 fileis what an edit costs: that file

Figures from the project README. Editors, compilers and runtimes see ordinary files, so builds run in the worktree unchanged.

How it works

No FUSE, no daemon, no virtual filesystem. A few hundred lines of bash and a small Python helper on top of git worktree and the filesystem's own block cloning.

  1. git worktree add --no-checkout

    Creates the worktree metadata and the branch, without writing files.
  2. cp -c -R (APFS clonefile)

    Clones every top-level entry of the base except .git, ignored directories included. A clone shares the base's blocks and costs zero bytes until one of them is written.
  3. git read-tree + update-index --refresh

    Populates the index without rewriting the clones. Only files that differ between the base and the target ref are checked out from git.
  4. .cowtree.toml

    Links the worktree back to its base, and the branch link is recorded in git config, so cowtree which works from any tool that reads git.

du cannot see block sharing, so ls and status report the bytes a worktree owns: files whose size or mtime differ from the base. On a filesystem without cloning, cowtree falls back to a plain copy and says so.

Six commands cover the day

One task, one worktree, one branch. Start with add, find things with ls and which, reset build output with clear, finish with rm or let sweep remove what merged. Output below is real.

cowtree add <base> <topic>

Clones the base into <wt_root>/<repo>-<topic> on branch <topic> and prints the path. --from, --branch, --exclude, --also.

$ cowtree add ~/code/myapp payments-retry
Preparing worktree (new branch 'payments-retry')
~/code/wt/myapp-payments-retry

cowtree which <branch>, branches

Which worktree holds a branch. The link lives in git config, so it survives without cowtree.

$ cowtree branches ~/code/myapp
main             (base)
payments-retry   ~/code/wt/myapp-payments-retry
search-index     ~/code/wt/myapp-search-index
$ cowtree which search-index ~/code/myapp
~/code/wt/myapp-search-index

cowtree ls [<base>] | --all

Every worktree of a base, or every cowtree worktree, with branch, logical size and the bytes it actually owns.

$ cowtree ls ~/code/myapp
~/code/myapp  (base)
~/code/wt/myapp-payments-retry  [payments-retry]  logical 301.0MB  owned 12.0KB
$ cowtree status wt/myapp-payments-retry
branch    payments-retry  (base on main)
changes   1 uncommitted
owned     12.0KB

cowtree clear <worktree>

Git tracks the source; everything ignored is build output. clear throws the worktree's ignored paths away and re-clones them from the base, so they match the base again and the blocks they owned are freed. Tracked files and their edits are never touched; untracked files that are not ignored are kept unless you pass --untracked. Alias: reset.

$ cowtree clear wt/myapp-checkout-v2 --dry-run
would reclone .next
would reclone node_modules
keep    NOTES.md  (untracked, not ignored; --untracked to reset it)
owned 42.6MB, would free about 42.6MB
$ cowtree clear wt/myapp-checkout-v2
reclone .next
reclone node_modules
keep    NOTES.md  (untracked, not ignored; --untracked to reset it)
owned 42.6MB -> 16.0KB
$ git -C wt/myapp-checkout-v2 status --short
 M app/page.tsx
?? NOTES.md

cowtree rm <worktree>, sweep

rm removes a worktree and deletes its branch if merged. sweep removes every clean worktree whose branch or GitHub PR merged, squash and rebase included.

$ cowtree sweep ~/code/myapp --dry-run
would remove ~/code/wt/myapp-fix-login [fix-login merged into main]
skip ~/code/wt/myapp-payments-retry (not clean)
$ cowtree rm wt/myapp-fix-login
deleted merged branch fix-login

Also: adopt and dedupe turn existing plain worktrees into clones, diff, workspace for a VS Code multi-root window, config. Full table in the README.

Built for Claude Code, Codex and Cursor

The repository is a Claude Code plugin: a skill that teaches the one-worktree-per-task rule, the /cowtree-add, /cowtree-status, /cowtree-clear and /cowtree-sweep commands, and an MCP server that exposes every command as a tool.

  • Claude Code: /plugin marketplace add paakofiaidoo/cowtree, then /plugin install cowtree.
  • Any MCP client (Codex, Cursor, Windsurf, Zed, Cline): python3 lib/mcp_server.py over stdio, standard library only.
  • Codex and AGENTS.md readers: cowtree agent-install codex.
  • Cursor: cowtree agent-install cursor --project . writes .cursor/rules/cowtree.mdc.
$ cowtree agent-install
$ cowtree agent-install --project .
{ "mcpServers": { "cowtree": {
    "command": "python3",
    "args": ["~/.cowtree/lib/mcp_server.py"] } } }

MCP tools: cowtree_add, cowtree_rm, cowtree_ls, cowtree_status, cowtree_diff, cowtree_branches, cowtree_which, cowtree_adopt, cowtree_clear, cowtree_sweep, cowtree_config.

Why cowtree

There are several ways to give each session its own working tree. A cowtree worktree is both: a real linked git worktree that shares history and branches with the base, and a copy-on-write clone of the whole checkout, ignored build directories included. Around that it keeps the bookkeeping parallel sessions need.

Plain git worktreeA second full cloneCopy-on-write copy of the whole directoryWorktree manager, copy-on-write for ignored files onlycowtree
One repository: shared history and branchesYesNo, a separate repositoryNo, a copy of the repository, .git includedYesYes
Checked-out source filesFull copyFull copyClones, 0 bytes until editedFull copyClones, 0 bytes until edited
node_modules, build/, .venvMissing, reinstallMissing, reinstallClonedClonedCloned
Which branch is in which treegit worktree listKept track of by youKept track of by youDepends on the toolwhich, branches, a link in git config
Reset build files to the base'sDelete and rebuildDelete and rebuildCopy the directory againDepends on the toolclear
Remove merged workBy handBy handBy handDepends on the toolsweep, squash-merged PRs too
Existing worktrees———Depends on the tooladopt and dedupe turn them into clones
Coding agents———Depends on the toolClaude Code plugin, MCP server, AGENTS.md and Cursor rules

A cowtree worktree is still a git worktree: git worktree list, VS Code and JetBrains see a normal checkout. Copy-on-write needs APFS on macOS or btrfs, XFS or bcachefs on Linux; the Linux reflink backend is written but not yet exercised on a Linux box, and elsewhere cowtree falls back to a plain copy and says so.

Install

Needs git 2.31 or newer, python3 and bash 3.2 or newer. The installer puts cowtree in ~/bin, writes ~/.config/cowtree/config.toml and wires up any coding agents it finds (COWTREE_AGENTS=0 to skip).

Linux reflink support (btrfs, XFS, bcachefs) is written but not yet exercised on a Linux box; reports are welcome.

brew install paakofiaidoo/tap/cowtree
curl -fsSL https://raw.githubusercontent.com/paakofiaidoo/cowtree/main/install.sh | bash

Source, issues and contributing notes are on GitHub; the formula lives in the Homebrew tap.