rimo-tools

claude-plugin-auto-worktree

A Claude Code plugin that automatically redirects Claude into a git worktree before modifying files, enabling safe parallel work without git conflicts.

Problem

When multiple Claude Code sessions work on the same repository simultaneously, file modifications can conflict. Non-engineers who aren't familiar with git branching may lose work or encounter confusing merge conflicts.

Design Policy

During normal use, code changes happen in worktree branches. This is a guiding principle, not a hard enforcement on every command.

The plugin is designed to be minimally invasive:

• Write/Edit to tracked files in the main repo are blocked — Claude is redirected to create a worktree first
• Bash commands are almost entirely allowed — only output redirects (>, >>) to tracked repo files are blocked
• Git commands (checkout, reset, merge, rebase, stash, etc.) are always allowed — the current main branch is not assumed to be correct, and users may need to fix or manage it
• Package managers, system commands, file utilities are all allowed
• Writes to /tmp, gitignored paths, or files outside the repo are always allowed (Plan Mode, memory, temp files all work)

Solution

This plugin intercepts Write, Edit, and Bash tool calls via a PreToolUse hook. When Claude tries to write or edit a tracked file in the main repository, the plugin:

1. Blocks the modification (exit code 2)
2. Instructs Claude to call the built-in EnterWorktree tool
3. Claude creates an isolated worktree and retries the action there

Each Claude session gets its own isolated worktree and branch, so parallel sessions never conflict.

Installation

From GitHub (recommended)

In Claude Code, run:

/plugin marketplace add rimoapp/claude-plugin-auto-worktree
/plugin install auto-worktree@rimoapp-plugins

Once installed, the plugin persists across sessions. You can enable/disable it anytime:

/plugin disable auto-worktree@rimoapp-plugins
/plugin enable auto-worktree@rimoapp-plugins

From local directory

For development or testing:

claude --plugin-dir /path/to/claude-plugin-auto-worktree

How It Works

User starts Claude in main repo
         │
         ▼
SessionStart hook fires ─── On default branch? → Proactively tells Claude to use EnterWorktree
         │
         ▼
Claude calls EnterWorktree → creates .claude/worktrees/<name>/
         │
         ▼
All file modifications happen safely in the worktree
         │
         ▼
Session ends → Stop hook prints summary (branch, uncommitted changes)

If Claude skips the proactive instruction, the PreToolUse hook acts as a safety net:

Claude tries to Write/Edit a file on default branch
         │
         ▼
PreToolUse hook intercepts ──────── Already in a worktree? → Allow
         │
         ▼
Blocks action (exit 2) + tells Claude to call EnterWorktree

Worktree Location

Worktrees are created by Claude Code's built-in EnterWorktree tool inside the repository:

my-project/
├── .claude/
│   └── worktrees/
│       ├── humble-prancing-conway/    # Session 1
│       └── brave-dancing-turing/      # Session 2
├── src/
└── ...

Each worktree gets a branch named worktree-<session-name>.

Bash Command Filtering

The plugin only blocks Bash commands that use output redirects (>, >>) to write to tracked files inside the repository. Everything else is allowed:

• Allowed: all commands without redirects (git checkout, npm install, rm, touch, mv, etc.), redirects to /tmp, /dev/null, gitignored files, or paths outside the repo
• Blocked: echo "data" > tracked-file.txt, cat input >> src/main.py, etc. (redirects to tracked repo files)

Configuration

The plugin supports user-configurable options via Claude Code's userConfig mechanism. After installing the plugin, you can set these options in your ~/.claude/settings.json under pluginConfigs:

Option	Description	Default
skip_directories	Comma-separated list of git repository root paths where auto-worktree should not activate	(empty)
pull_default_branch	Pull the latest default branch from origin on session start. Uses fast-forward only — local changes are never overwritten. Silently continues on failure.	true
sync_gitignored_writes	Automatically copy gitignored files written in a worktree back to the main repository. Covers Write/Edit tool calls and Bash output redirects.	true

Example settings.json

{
  "pluginConfigs": {
    "auto-worktree@rimoapp-plugins": {
      "options": {
        "skip_directories": "/Users/me/notes,/Users/me/scratch",
        "pull_default_branch": "false",
        "sync_gitignored_writes": "true"
      }
    }
  }
}

skip_directories