Get started

Install iso-code in under 3 minutes.

iso-code ships as three packages: a Rust library, a CLI, and an MCP server. Pick the one that matches what you're doing and you'll be running your first safe worktree in a couple of commands.

Which package do I want?

All three packages use the same underlying library, so all three enforce the same safety guards. The only difference is how you call in.

If you…Install this
Run an AI coding agent (Claude Code, Cursor, VS Code, OpenCode) and want it to manage worktrees safelyiso-code-mcp
Want a wt command in your terminal or shell scriptsiso-code-cli
Are writing a Rust tool that needs to create, list, or delete worktreesiso-code

Prerequisites

That's it. No daemons, no background service, no database.

1Path A — Agent user (MCP)

Install the server:

cargo install iso-code-mcp

Then point your agent at it. Pick the config that matches your tool:

Claude Code

// ~/.claude.json
{
  "mcpServers": {
    "iso-code": {
      "command": "iso-code-mcp",
      "args": []
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "iso-code": { "command": "iso-code-mcp" }
  }
}

VS Code

// .vscode/mcp.json
{
  "servers": {
    "iso-code": { "type": "stdio", "command": "iso-code-mcp" }
  }
}

OpenCode

// opencode.json
{
  "mcp": {
    "servers": {
      "iso-code": { "type": "local", "command": ["iso-code-mcp"] }
    }
  }
}

Restart your agent. Now ask it:

"Create a worktree for a new branch called feature/try-isocode, then delete it."

The agent will use worktree_create and worktree_delete for that prompt. The full tool set is worktree_list, worktree_status (branch, state, disk usage per worktree), worktree_create, worktree_delete, and worktree_gc — every call goes through the same safety guards as the library and CLI.

2Path B — CLI user (wt)

Install the CLI:

cargo install iso-code-cli

Then run a full lifecycle against a repo you already have:

cd /path/to/your/repo

# List — should show just your main worktree
wt list

# Create — makes a new worktree one level up
wt create feature/try-isocode ../try-isocode

# Verify it exists
wt list

# Clean it up — runs the 5-step unmerged-commit check first
wt delete ../try-isocode

That's the whole lifecycle. The commands you'll use day-to-day are list, create, delete, and gc (run with --run to actually evict; default is a dry-run preview).

3Path C — Rust library

Add the crate:

cargo add iso-code

Minimal program:

use iso_code::{Manager, Config, CreateOptions, DeleteOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mgr = Manager::new("/path/to/your/repo", Config::default())?;

    let (handle, _) = mgr.create(
        "feature/try-isocode",
        "/tmp/try-isocode",
        CreateOptions::default(),
    )?;

    for wt in mgr.list()? {
        println!("{:?}", wt);
    }

    mgr.delete(&handle, DeleteOptions::default())?;
    Ok(())
}

Build and run it with cargo run. Same safety guards, same state file on disk — the CLI and MCP server are thin wrappers around exactly this API.

What just happened

That last delete call — whichever path you took — ran these checks before removing anything:

None of this needed configuration. Safe by default is the whole point.

Tip: If you want to see the guards actually fire, create a branch with an unpushed commit, then try wt delete against it. You'll get unmerged commits on 'your-branch': N commit(s) not in upstream — use force to override, and the worktree directory stays on disk.

Where to go next