The Problem

Developers running multiple AI agents often need separate Git worktrees so each agent can work without stepping on another’s changes. The native git worktree workflow requires repetitive commands and manual path handling, making large‑scale parallel experimentation cumbersome and error‑prone.

What This Does

Worktrunk provides a thin CLI that treats a worktree as a branch name. Core commands (wt switch, wt add, wt remove, wt list) translate branch identifiers into concrete worktree paths using a configurable template (.config/wt.toml).

  • The binary lives in src/main.rs (entry point) and src/lib.rs.
  • Command implementations are in src/commands/ – e.g. src/commands/switch.rs, src/commands/list/mod.rs, src/commands/worktree/add.rs.
  • Hook support and LLM‑driven commit generation are in src/llm.rs and src/commands/commit.rs.

Documentation, demos, and reference pages are in docs/ and the README.md illustrates the same command set.

How It Is Wired

Execution starts at fn main() in src/main.rs:92. main parses CLI arguments (via clap) and dispatches to the appropriate command module, reaching 401 distinct functions.

  • The most‑used internal utilities are output (called from 249 places) and run_git (139 places). Both reside in src/git/ and wrap external git invocations.
  • A typical wt switch flow:
  1. main → dispatch → src/commands/switch.rs::run_switch.
  2. run_switch calls src/git/repository/mod.rs::at to locate the repository, then src/commands/worktree/add.rs::add_worktree.
  3. add_worktree invokes run_git (via src/git/commands.rs) which spawns a subprocess (git worktree add …).
  • Filesystem writes (e.g., creating a worktree directory) happen in src/commands/worktree/add.rs via std::fs::create_dir_all.
  • LLM‑driven commit prompts are built in src/llm.rs::build_commit_prompt and called from src/commands/commit.rs::step_commit, reaching an external model through the llm crate.

The hub modules—src/shell_exec.rs (63 functions, called from 82 files) and tests/common/mod.rs (136 functions, called from 61 files)—carry the widest blast radius because many commands route through them for process execution and test utilities.

No circular import cycles were detected; the import graph contains 7 internal modules with only 3 edges, indicating a relatively flat dependency structure.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/worktrunk
cd worktrunk

# Build the CLI (Rust toolchain required)
cargo build --release

# Optional: copy the example config
cp .config/wt.toml.example .config/wt.toml   # (file present in repo)

# Create a worktree named "feat"
./target/release/worktrunk switch -c feat   # -c also starts Claude if configured

# List all worktrees with status symbols
./target/release/worktrunk list

Configuration lives in .config/wt.toml; the template for worktree paths can be edited there. No additional environment variables are required for basic operation.

Real‑World Use

A data‑science team runs ten independent Claude agents on a monorepo. Each agent executes wt switch -c <branch> to spin up its own worktree, runs its training script, then commits results via wt commit. Worktrunk isolates filesystem state per agent while keeping a single Git history, reducing merge conflicts and simplifying cleanup (wt remove).

Code Health & Issues

  • Critical – Secrets in workflow: .github/workflows/claude-ci-fix.yaml contains WORKTRUNK_BOT_TOKEN and CLAUDE_CODE_OAUTH_TOKEN. Pull‑request code can access these tokens.
  • High – Actions not pinned: several GitHub Actions use tag references (@v2, @latest). Replace with full commit SHA to prevent supply‑chain hijack.
  • High – Release workflow pushes directly to default branch. Switch to a bot branch and open a PR to ensure CI runs on the exact commit that will be released.
  • Medium – No dependency‑vulnerability scan in CI. Add dependency-review-action or osv-scanner.
  • Low – Workflow jobs lack timeout-minutes; add reasonable limits to avoid hung runs.

The static analysis also flagged three high‑severity maintainability concerns: deep nesting (max depth 9 in benches/list.rs), duplicated 6‑line blocks across ~50 files, and oversized files (>1 k lines) such as src/config/deprecation.rs. Refactoring these would improve readability and reduce change‑impact risk.

The Bottom Line

Worktrunk delivers a focused CLI that abstracts Git worktree management into branch‑centric commands, backed by a well‑structured Rust codebase and extensive test coverage. Immediate attention should be given to CI secret handling and action pinning before using it in production, but the core functionality is solid for teams needing isolated workspaces for parallel AI agents.