Agent skill

worktree-task

使用 git worktree + 背景代理会话管理大型任务（默认启动 Claude Code；可用 --codex 快速切到 Codex CLI，或通过 --agent-cmd 指定任意命令）。适合用户希望在不阻塞当前会话的情况下执行大型或多步骤任务。

View SKILL.md on GitHub Repository
Stars 39
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/ourines/worktree-task-plugin/tree/main/skills/worktree-task

SKILL.md

Worktree Task Manager

This skill manages large coding tasks by spawning autonomous agent instances (默认 Claude Code，可选 --codex/--agent-cmd) in separate git worktrees via tmux sessions.

When to Use

  • User wants to execute a large task (>20 subtasks) without blocking current session
  • User mentions "background", "parallel", "worktree", or "autonomous" execution
  • Task involves creating a new service, major refactoring, or implementing complex features
  • User wants to continue other work while a large task runs

Available Commands

Use these slash commands for precise control:

Command Description
/worktree:launch Launch a new background task
/worktree:status Check status of all or specific tasks
/worktree:resume Resume an interrupted task
/worktree:cleanup Clean up completed tasks

Core Workflow

1. Launch a Task

bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/launch.py <branch-name> "<task-description>"

Example:

bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/launch.py feature/my-task "Execute the task: implement new feature. Read the tasks.md and implement all phases."

The script will:

  1. Verify git status is clean (or prompt to commit/stash)
  2. Create a git worktree with the specified branch
  3. Create a tmux session
  4. Launch Claude Code by default (use --codex for default Codex command or --agent-cmd to switch, e.g., codex --yolo -m gpt-5.1-codex-max -c model_reasoning_effort="high")
  5. Send the task with instructions to use Task tool for each phase

2. Monitor Progress

bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/status.py [session-name]

Without arguments, lists all active sessions. With a session name, shows detailed status.

3. Resume an Interrupted Task

If a task is interrupted (rate limit, API error, timeout):

bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/resume.py <session-name> [message]

Options:

  • --retry - Retry the last failed task
  • --check - Only check status, don't send message

4. Cleanup

bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup.py <session-name> [--remove-worktree]

Alerts

This plugin automatically sends macOS notifications when:

  • A background task completes successfully
  • A task encounters an error (rate limit, API error)
  • A session ends

Configure alerts in hooks/hooks.json.

Critical Instructions for Spawned Claude

The spawned agent receives these critical instructions:

  1. MUST use Task tool - Each major phase must be executed via Task tool to prevent context overflow
  2. Silent mode - No confirmations needed, user has pre-approved all operations
  3. Complete execution - Do not stop until all tasks are done
  4. Track with TodoWrite - Create and update todo list for visibility
  5. Commit often - Make atomic commits after each logical unit

Notes

  • Worktrees are created in parent directory: ../<project>-<branch-name>
  • tmux session names have / and . replaced with -
  • Use tmux attach -t <session> to take over interactively
  • The spawned Claude runs with full permissions (--dangerously-skip-permissions)

💡 More Claude Code plugins: github.com/ourines

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

mattpocock/skills

git-guardrails-claude-code

Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.

111,310 9,758
Explore
mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758
Explore
mattpocock/skills

setup-pre-commit

Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

111,310 9,758
Explore
mattpocock/skills

handoff

Compact the current conversation into a handoff document for another agent to pick up.

111,310 9,758
Explore
mattpocock/skills

scaffold-exercises

Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

111,310 9,758
Explore
mattpocock/skills

obsidian-vault

Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results