Crate iso_code 

iso-code

Safe git worktree lifecycle management for AI coding agents.

iso-code is a Rust library + CLI + MCP server that solves documented data-loss bugs in Claude Code, Cursor, Claude Squad, OpenCode, and VS Code Copilot by providing a shared, battle-tested worktree management foundation.

Problem

Every major AI coding orchestrator independently implements worktree management and each has critical bugs:

• Silent data loss (unmerged commits deleted without warning)
• Unbounded resource consumption (hundreds of orphaned worktrees)
• Nested worktree creation after context compaction
• git-crypt corruption on worktree creation

iso-code fixes all of these with a single shared library.

Installation

[dependencies]
iso-code = "0.1"

CLI:

cargo install iso-code-cli

Basic Usage

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

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

    // Create a worktree
    let (handle, _) = mgr.create("feature/my-branch", "/path/to/worktree", CreateOptions::default())?;

    // List all worktrees
    let worktrees = mgr.list()?;

    // Delete safely (runs 5-step unmerged commit check)
    mgr.delete(&handle, DeleteOptions::default())?;

    // GC orphaned worktrees (dry_run = true by default)
    let report = mgr.gc(Default::default())?;
    Ok(())
}

CLI

wt list
wt create feature/my-branch /path/to/worktree
wt delete /path/to/worktree
wt hook --stdin-format claude-code   # Claude Code hook integration

MCP Server Configuration

Claude Code (~/.claude/claude_desktop_config.json)

{
  "mcpServers": {
    "iso-code": {
      "command": "iso-code-mcp",
      "args": []
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "iso-code": {
      "command": "iso-code-mcp"
    }
  }
}

VS Code Copilot (.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"]
      }
    }
  }
}

Claude Code Hook Integration

Add to your Claude Code config:

{
  "hooks": {
    "WorktreeCreate": "wt hook --stdin-format claude-code --setup"
  }
}

Safety Guarantees

• Never deletes branches with unmerged commits (5-step check)
• Never leaves partial worktrees on disk (cleanup-on-failure)
• Never corrupts git-crypt repos (post-create verification)
• Never creates nested worktrees (bidirectional path check)
• Never evicts locked worktrees (unconditional protection)
• State.json is crash-safe (atomic write via tmp + fsync + rename)

License

Licensed under either of Apache License 2.0 or MIT License at your option.

Re-exports

pub use error::WorktreeError;

pub use manager::Manager;

pub use types::AttachOptions;

pub use types::Config;

pub use types::CopyOutcome;

pub use types::CreateOptions;

pub use types::DeleteOptions;

pub use types::EcosystemAdapter;

pub use types::GcOptions;

pub use types::GcReport;

pub use types::GitCapabilities;

pub use types::GitCryptStatus;

pub use types::GitVersion;

pub use types::PortLease;

pub use types::ReflinkMode;

pub use types::WorktreeHandle;

pub use types::WorktreeState;

Modules

error

git

guards

Pre-create and pre-delete safety guards.

lock

Hardened locking protocol for state.json.

manager

platform

ports

Port lease allocation.

state

State persistence: state.json v2 read/write/migrate.

types

util

Shared filesystem helpers: directory-size walk and filesystem-capacity probe.