# Issue Worktree Agent

> Skill for creating and managing isolated git worktrees (`.worktrees/issue-NNN`) for issue execution branches. USE ONLY when setting up or cleaning up isolated git worktrees for specific issue execution. DO NOT USE for managing local task files (use `task-agent`) or escalating tasks to issues (use `github-issue-backlog-agent`).

- Skill: `richfrem/issue-worktree-agent` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add richfrem/issue-worktree-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/richfrem/issue-worktree-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: richfrem (https://skillmd.com/u/richfrem)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/richfrem/issue-worktree-agent

---


# Issue Worktree Agent (`issue-worktree-agent`)

> **Routing Directive:** USE ONLY when setting up, listing, or removing isolated git worktrees (`.worktrees/issue-NNN`) for issue execution branches. DO NOT USE for managing local scratch tasks (use `task-agent` instead) or managing GitHub PR lifecycles (use `issue-pr-lifecycle-agent` instead).

The `issue-worktree-agent` skill manages isolated workspace environments using `git worktree`. It ensures agent work on specific issues takes place in isolated branches under `.worktrees/issue-NNN` without dirtying or interfering with the main working directory.

---

## Safety & Security Contracts

1. **Path Isolation:** All worktrees created by this skill are strictly scoped within `.worktrees/issue-NNN`.
2. **Branch Management:** Automatically creates feature branches named `issue-NNN` (or a custom branch name) off a specified base branch (default: `main`).
3. **Safe Cleanup:** Worktree removal requires explicit call; supports `--force` flag for uncommitted change cleanup.

---

## Usage catalog

### Create, List, and Remove Worktrees

- **Helper Script:** `plugins/dev-utils/skills/issue-worktree-agent/scripts/issue_worktree_manage.py`
- **CLI Usage:**
  ```bash
  # Create a worktree for Issue #123:
  python3 plugins/dev-utils/skills/issue-worktree-agent/scripts/issue_worktree_manage.py create --issue 123 --base main

  # List active worktrees:
  python3 plugins/dev-utils/skills/issue-worktree-agent/scripts/issue_worktree_manage.py list

  # Remove a worktree for Issue #123:
  python3 plugins/dev-utils/skills/issue-worktree-agent/scripts/issue_worktree_manage.py remove --issue 123
  ```

---

## Python API Interface

```python
from plugins.dev_utils.skills.issue_worktree_agent.scripts.issue_worktree_manage import (
    create_worktree,
    list_worktrees,
    remove_worktree,
)

# Create worktree
res = create_worktree(issue_number=123, branch_name="fix-issue-123", base_branch="main")

# List worktrees
worktrees = list_worktrees()

# Remove worktree
remove_worktree(issue_number=123, force=False)
```