treefork

Workspace isolation for AI agents using git worktrees. Give each agent its own branch and directory — no conflicts, no coordination overhead.

Treefork is a small TypeScript library and CLI. It wraps git worktree with a clean API for creating, listing, snapshotting, and removing isolated workspaces. Works with local repos and remote git URLs.

Install

bun add treefork

CLI

# Create or reuse a workspace (prints its path)
treefork create my-feature

# Create from a specific ref
treefork create my-feature --base main

# Create from a remote git URL
treefork create my-feature --repo git@github.com:acme/service.git

# Create and open the workspace in tmux
treefork create my-feature --tmux-window
treefork create my-feature --tmux-session quire
treefork create my-feature --tmux-session

# List all workspaces
treefork list

# Get the path of a workspace
treefork resolve my-feature

# Remove a workspace
treefork remove my-feature
treefork remove my-feature --force

Checkpoints

Snapshot and restore workspace state:

# Save a checkpoint
treefork checkpoint create my-feature before-refactor

# List checkpoints
treefork checkpoint list my-feature

# Restore a checkpoint
treefork checkpoint restore my-feature before-refactor

# Restore and clean untracked files
treefork checkpoint restore my-feature before-refactor --clean

Library

import { createTreefork } from "treefork";

// From a local repo
const treefork = await createTreefork();

// From a remote git URL
const remote = await createTreefork({
  repo: "git@github.com:acme/service.git",
});

Workspaces

// Create a workspace — returns { name, path, branch, head }
const ws = await treefork.workspaces.create({ name: "agent-1" });
console.log(ws.path); // /Users/you/code/../.myrepo-treefork/agent-1

// List all workspaces
const all = await treefork.workspaces.list();

// Resolve a single workspace (returns null if not found)
const found = await treefork.workspaces.resolve({ name: "agent-1" });

// Remove a workspace
await treefork.workspaces.remove({ name: "agent-1" });
await treefork.workspaces.remove({ name: "agent-1", force: true });

Checkpoints

// Snapshot the current state
const cp = await treefork.checkpoints.create({
  workspace: "agent-1",
  name: "before-refactor",
});

// List checkpoints for a workspace
const checkpoints = await treefork.checkpoints.list({ workspace: "agent-1" });

// Restore a checkpoint
await treefork.checkpoints.restore({
  workspace: "agent-1",
  name: "before-refactor",
  clean: true, // optional: remove untracked files
});

Configuration

Pass options to createTreefork to override defaults:

const treefork = await createTreefork({
  cwd: "/path/to/repo",
  storageDir: "../custom-storage",
  defaultBaseRef: "main",
  branchPrefix: "treefork/",
  checkpointRefPrefix: "refs/treefork/checkpoints",
});

Or use a treefork.config.json file (searched upward from cwd, then ~/.config/treefork/config.json):

{
  "storageDir": "../.my-workspaces",
  "defaultBaseRef": "main"
}

How it works

Local mode — each workspace is a git worktree stored in a sibling directory (../.{repoName}-treefork/). Branches are namespaced under treefork/ and checkpoints are stored as git refs under refs/treefork/checkpoints/.

Remote mode — when repo is set, treefork creates a bare clone of the remote URL under the storage directory (.treefork/.mirrors/), then creates worktrees from it. The bare clone is fetched on initialization to stay current. Branches and checkpoint refs live in the bare clone, not on the remote.

tmux integration — treefork create <name> --tmux-window creates or reuses the workspace and opens or reuses a window named <name> in the current tmux session. treefork create <name> --tmux-session <session> creates or reuses a tmux session and opens or reuses a window named <name> there. treefork create <name> --tmux-session uses <name> as the tmux session name. Treefork operates on the current repo; callers are responsible for running it from the repo they want to fork.

Alternatives

gtr (git-worktree-runner) — a batteries-included Bash CLI for managing git worktrees. It has editor launching, AI tool integration, shell completions, file copying, hooks, and team config via .gtrconfig. If you want a full-featured interactive tool for your terminal, gtr is excellent.

Treefork is different in intent: it's a headless library first with a minimal CLI second. There's no editor/AI integration, no shell hooks — just programmatic primitives for tools that manage workspaces on behalf of the user. If you're building an AI coding tool or orchestrator and need to embed worktree management, treefork gives you a typed API with checkpointing. If you're a developer who wants a better git worktree experience in your shell, use gtr.

License

MIT