Findings, rationale, and validation work from building safe git worktree primitives for AI coding agents.
A library that promises safety only matters if someone has tested it under conditions that look like reality. Here's the methodology, the numbers, and the gaps for iso-code v0.1.1.
Before celebrating the v0.1.1 release, we ran 80 lifecycle checks against the published binaries on five real-world repositories. Three things broke. We filed them against ourselves.
iso-code is a safety layer between AI coding agents and git worktrees. It ships as a Rust library, a wt CLI, and an iso-code-mcp MCP server — all three enforce the same safety guards (5-step unmerged-commit check, symlink-safe recursion, crash-safe state, circuit breaker, port leases) on every worktree create, delete, and garbage-collect.
If you run an AI coding agent (Claude Code, Cursor, VS Code, OpenCode), install iso-code-mcp. If you want a wt command in your terminal or shell scripts, install iso-code-cli. If you're writing a Rust tool that manages worktrees, add iso-code to Cargo.toml. All three share the same library underneath.
The getting started guide walks through each path in ~3 minutes.
git worktree?No. iso-code shells out to the git you already have installed. It never reimplements git semantics — git worktree list --porcelain is always authoritative, and iso-code's state.json is just a cache. If they ever disagree, git wins.
iso-code-mcp is a standard stdio MCP server, so any MCP-aware orchestrator can use it. Tested configurations exist for Claude Code, Cursor, VS Code, and OpenCode. It was built specifically to fix documented data-loss bugs in those tools and Claude Squad.
Yes. iso-code only operates on worktrees you explicitly create or attach — it never touches your main checkout. State writes are atomic (tmp + fsync + rename) and OS-level file locks prevent concurrent corruption. If iso-code crashes mid-operation you are left either fully in or fully out, never half.
Negligible. In the v0.1.1 test pass against five real-world repos, create times ranged from 164 ms on flask (2.4 MB) to 3.5 s on next.js (246 MB). Delete times scale linearly with working-tree size — that's filesystem-bound, not iso-code overhead. Safety checks themselves add sub-millisecond cost. Full numbers are in the test methodology post.
No. iso-code is a library, a CLI, and a stdio MCP server. There is no daemon, no background service, and no database. State lives in .git/iso-code/state.json next to the repo it manages.
Dual-licensed Apache-2.0 OR MIT. Pick whichever fits your project.