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.
bun add treeforkWith treefork on your PATH, run the one-time shell setup:
treefork setupSetup supports bash and zsh. It asks before adding a marked initialization line to your shell profile, preserves existing settings, and can be run again without duplicating that line. Use --shell bash or --shell zsh to select a shell explicitly, or --yes to approve the edit without prompting. Zsh uses ${ZDOTDIR:-$HOME}/.zshrc; bash uses ~/.bashrc on Linux. On macOS, bash uses the first existing login profile (~/.bash_profile, ~/.bash_login, or ~/.profile), defaulting to ~/.bash_profile if none exists.
Follow the printed activation command for your current terminal (or open a new terminal):
eval "$(treefork init zsh)" # use bash for a bash shell
tf my-featuretf <name> creates or reuses a workspace and changes your current shell's directory into it. Creation errors leave your directory unchanged. Options such as tf my-feature --base main are forwarded to create; help and tmux options run the underlying command without navigating the calling shell. tf is a workspace-entry function, not a shorthand for all subcommands: use treefork list, not tf list (which creates a workspace named list). An existing tf alias, function, or executable is not overwritten.
For manual installation, add eval "$(treefork init bash)" or eval "$(treefork init zsh)" to your shell profile. To uninstall, remove the marked # treefork shell integration line and open a new terminal. Setup does not change w
A92A
orktree storage preferences.
treefork create remains available when you want to create a workspace without entering it, or when working with scripts, agents, and tmux. When stdout is captured or piped, create and resolve print only the absolute path. Interactive output shortens paths under your home directory; a one-time setup hint appears after an ordinary interactive create when integration is not loaded.
# Create or reuse a workspace without entering it
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 --forceSnapshot 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 --cleanimport { 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",
});// 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 });// 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
});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"
}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.
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.
MIT