claude-agent-worktrees

Claude Agents And Worktrees

Use this skill for Claude Code session orchestration: background agents, worktrees, tmux/iTerm panes, resumes, PR-linked sessions, forked sessions, session names and IDs, remote control, prompt suggestions, and cloud ultrareview.

From this skill directory, the plugin root is ../...

Inspect First

Check command surface and current background sessions:

python3 ../../scripts/claude_code_inspector.py --commands agents ultrareview --json
claude agents --json

Use claude agents --json --all only when completed sessions are relevant and the extra transcript/session metadata is needed.

Background Agents

Use claude agents for active background session state and dispatch defaults:

claude agents --json
claude agents --cwd /path/to/project --json
claude agents --model sonnet --permission-mode plan --add-dir /path/to/extra

Do not start or leave long-lived background sessions without a reason and a cleanup plan. Use explicit model, permission mode, settings, plugin-dir, and MCP config when reproducibility matters.

Sessions

Use these root flags for session continuity:

claude --continue
claude --resume <session-id-or-search>
claude --from-pr <pr-number-or-url>
claude --fork-session --resume <session-id>
claude --session-id <uuid>
claude --name "display-name"

Prefer exact session IDs or PR URLs when the user wants a specific conversation. Use search/pickers only for interactive use.

Worktrees And Panes

Use worktrees when the task should be isolated from the current working tree:

claude --worktree
claude --worktree feature-name --tmux
claude --worktree feature-name --tmux=classic

Before creating worktrees, inspect git status and branch state. Do not create extra worktrees for tiny one-off commands unless isolation is the point.

Remote Control And Integrations

Remote control, IDE, and Chrome integration are interactive surfaces:

claude --remote-control
claude --remote-control "session-name"
claude --ide
claude --chrome
claude --no-chrome

Use them only when the user asks for those integrations. Report how to stop or exit any interactive session started.

Ultrareview

claude ultrareview is cloud-hosted and may consume time or quota. Run it only when requested:

claude ultrareview
claude ultrareview main
claude ultrareview <pr-number-or-url> --json --timeout 30

Prefer local review or --print analysis for lightweight checks.

Safety Boundaries

• Do not combine background dispatch with dangerous skip-permissions unless the user selected an external sandbox.
• Do not create worktrees, tmux sessions, or remote-control sessions without clear user intent.
• Do not purge or abandon background work without reporting the session state.
• Do not expose session IDs, PR URLs, or transcript snippets beyond what the user needs.

Completion Standard

Report the current session/agent/worktree state inspected, exact command used, permission/tool settings, any created session/worktree/pane name, and cleanup or resume instructions when a process remains active.