Bob Worktrees

Git worktree management for parallel development — powered by IBM Bob IDE

Work on multiple features simultaneously in fully isolated git worktrees, managed by natural-language commands inside IBM Bob IDE.

🎥 Demo

▶ Watch the demo video

📦 Download

| | Link | |---|---| | npm package | bob-worktrees-2.1.0.tgz | | Install skill (IBM Bob) | worktrees/SKILL.md | | Install via skills CLI | npx skills add Kunal-Gola/bob-worktrees --skill worktrees | | Install npm globally | npm install -g bob-worktrees | | IBM Propel marketplace | View on Propel |

How it works

You (in Bob IDE)  ──▶  Bob Skill (worktrees)
                              │
                              ▼
                    MCP server (bob-worktrees npm)
                              │
                              ▼
                    git worktree add / remove / merge
                              │
                              ▼
               ~/.bob-worktrees/<repo>/<branch>-<ts>/

The bob-worktrees npm package ships two things:

| Component | What it does | |---|---| | MCP server (mcp-server/index.js) | Runs at Bob IDE startup; exposes worktree tools over stdio MCP | | CLI (bob-worktree) | Same operations from a terminal, no IDE needed |

The Bob Skill (worktrees) is the glue that teaches Bob how to call those tools and recover when things go wrong.

🚀 Quickstart — Recommended (Skill-first)

Prerequisite: IBM Bob IDE with internet access to install npm packages.

Step 1 — Install the skill in Bob IDE

Option A — skills CLI (recommended, works in any AI agent):

npx skills add Kunal-Gola/bob-worktrees --skill worktrees --global

This uses the Agent Skills open format — same skill works in IBM Bob, Claude Code, Cursor, Codex, and more.

Option B — manual download:

⬇ Download worktrees/SKILL.md

Save it to ~/.bob/skills/worktrees/SKILL.md.

Option C — tell Bob (if already in IBM Bob IDE):

"Install the worktrees skill from https://github.ibm.com/Kunal-Gola/bob-worktrees"

The skill will guide you through the rest of the setup interactively.

Step 2 — Install the npm package

Open a terminal (or ask Bob to run this for you):

npm install -g bob-worktrees

postinstall automatically writes the MCP server entry to ~/.bob/settings/mcp.json.

Step 3 — Restart Bob IDE

Bob IDE reads MCP config at startup. One restart loads the server.

Step 4 — Use it

Open any git repo in Bob IDE and say:

"List my git worktrees" "Create a worktree for feature/auth" "Merge feature/auth into main" "Delete the feature/auth worktree"

📦 npm package

npm install -g bob-worktrees

What the postinstall script does

• Finds the absolute path to the running node binary (works with nvm, fnm, volta, homebrew, system)
• Writes an entry to ~/.bob/settings/mcp.json (Bob IDE's global MCP config):

{
  "mcpServers": {
    "bob-worktrees": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/bob-worktrees/mcp-server/index.js"]
    }
  }
}

Using absolute paths means the server starts correctly even in Bob IDE's non-shell environment (no PATH lookup).

🛠 MCP tools

These are the tools the MCP server exposes. Bob calls them automatically; you can also call them explicitly in a task.

| Tool | Required args | What it does | |---|---|---| | list_worktrees | — | List all worktrees for the open repo | | create_worktree | branch | Create a new worktree (optionally: base_branch, custom_path) | | delete_worktree | branch | Remove a worktree by branch name (optionally: force) | | get_worktree_status | branch | Show git status + recent commits for a worktree | | merge_worktree | source_branch, target_branch | Two-phase merge: detect conflicts first, then execute | | switch_worktree | branch | Get the filesystem path of a worktree |

All tools accept an optional repo_path. If omitted, the server resolves the repo automatically from BOB_PROJECT_DIR (set by Bob IDE) or by walking up from the current directory.

Merge is always two-phase

Phase 1 (detect_only: true)  ──▶  returns conflict_files[], has_conflicts
Phase 2 (detect_only: false) ──▶  executes merge with per-file resolutions

Bob will never execute Phase 2 without showing you the conflict list first.

💻 CLI reference

The bob-worktree CLI is installed alongside the npm package.

bob-worktree list                              # List all worktrees
bob-worktree create <branch> [--base <branch>] # Create worktree
bob-worktree status <branch>                   # Git status + recent commits
bob-worktree merge <source> <target>           # Interactive merge
bob-worktree delete <branch> [--force] [--yes] # Delete (--yes skips prompt)
bob-worktree --help                            # Full help

Worktrees are stored under ~/.bob-worktrees/<repo-name>/. Override with BOB_WORKTREE_ROOT env var.

📁 Repo layout

cli/
  index.js          ← CLI entry point (commander, ES module)
  commands.js       ← All CLI command implementations
mcp-server/
  index.js          ← MCP server (ES module, BOB_PROJECT_DIR-aware)
scripts/
  postinstall.js    ← Writes ~/.bob/settings/mcp.json on npm install -g
  health-check.cjs  ← Quick dependency / config health check
.bob/
  skills/worktrees/SKILL.md  ← Bob skill (install this in Bob IDE)
skill/
  worktrees-skill.md         ← Same skill, bundled inside the npm package
hooks/
  setup_worktree.sh ← Optional post-create hook (npm install in new worktree)
tests/             ← Node built-in test runner (no extra deps)

⚙️ Requirements

• Node.js ≥ 18
• Git ≥ 2.5 (for git worktree)
• IBM Bob IDE (for skill + MCP integration)

🔧 Troubleshooting

MCP tools fail with "not a git repository"

The MCP server uses BOB_PROJECT_DIR (set by Bob IDE) to find the repo. Make sure:

1. You have a git repo open in Bob IDE
2. You restarted Bob IDE after installing the package

"command not found: bob-worktree"

The CLI binary is at $(npm root -g)/../bin/bob-worktree. Make sure your npm global bin is in PATH:

npm config get prefix    # e.g. /Users/you/.nvm/versions/node/v20.0.0
export PATH="$PATH:$(npm config get prefix)/bin"

MCP server entry missing from config

Re-run postinstall manually:

node $(npm root -g)/bob-worktrees/scripts/postinstall.js

Then restart Bob IDE.

Worktree has modified files, delete fails

bob-worktree delete <branch> --force

🧪 Tests

npm test   # runs tests/postinstall.test.js + tests/mcp-server.test.js

🤝 Contributing

See CONTRIBUTING.md.

📝 License

MIT — see LICENSE.

Copyright © 2026 IBM Data Core Agentic Engineering Guild