Spawns AI coding agents in isolated git worktrees. Use when the user asks to spawn or launch an agent, delegate a task to a separate agent, work in a separate worktree, or parallelize development across features.
npxskills add basnijholt/agent-cli--skill agent-cli-devLoading…
This skill teaches you how to spawn parallel AI coding agents in isolated git worktrees using the agent-cli dev command.
agent-cli dev supports two complementary patterns:
dev agent --tmux-session <unique-name> for autonomous launches, or -m tmux when a human explicitly wants shared tmux windowsIf agent-cli is not available, install it first:
# Install globally
uv tool install agent-cli
# Or run directly without installing
uvx agent-cli dev new <branch-name> --prompt "..."
Spawn separate agents when:
Do NOT spawn when:
For new features (starts from origin/main):
agent-cli dev new <branch-name> --prompt "Implement the new feature..."
For work on current branch (review, test, fix) - use --from HEAD:
agent-cli dev new <branch-name> --from HEAD --prompt "Review/test/fix..."
For longer prompts (recommended for multi-line or complex instructions):
agent-cli dev new <branch-name> --from HEAD --prompt-file path/to/prompt.md
This creates:
.claude/ in the worktree (for reference)Important: Use --prompt-file for prompts longer than a single line. The --prompt option passes text through the shell, which can cause issues with special characters (exclamation marks, dollar signs, backticks, quotes) in ZSH and other shells. Using --prompt-file avoids all shell quoting issues.
When an assistant is executing this workflow on the user's behalf, the spawn is not complete unless the agent receives a prompt at launch time.
--prompt-file; create the prompt file first, then launch the agentdev new ... --prompt-file ... for a new delegated taskdev agent ... --prompt-file ... for another agent in an existing worktreedev new ... alone if the user's intent was to delegate work immediatelydev new ... --start-agent, dev new ... --agent <name>, or dev agent ... -m tmux without --prompt or --prompt-file unless the user explicitly wants an interactive session that they will drive manuallySpawned agents work in isolation, so prompts must be self-contained. Include:
.claude/REPORT.mdFor any prompt longer than a single sentence:
.claude/spawn-prompt.md)--prompt-file to pass it to the agentExample workflow:
# 1. Write prompt to file
# 2. Spawn agent with the file
agent-cli dev new my-feature --prompt-file .claude/spawn-prompt.md
# 3. Optionally clean up
rm .claude/spawn-prompt.md
<Task description>
Context:
- <Key file locations>
- <Patterns to follow>
- <Constraints or requirements>
When complete, write a summary to .claude/REPORT.md including:
- What you implemented/changed
- Key decisions you made
- Any questions or concerns for review
After spawning, you can check progress:
# List all worktrees and their status
agent-cli dev status
# Read an agent's report
agent-cli dev run <branch-name> cat .claude/REPORT.md
# Open the worktree in your editor
agent-cli dev editor <branch-name>
Use this when several agents should inspect or validate the same code at once without separate worktrees.
# Create the worktree once. This step only prepares the shared workspace.
agent-cli dev new review-auth --from HEAD
# Then launch the actual agents with prompts. Give each agent its own tmux session.
agent-cli dev agent review-auth \
--tmux-session review-auth-security-20260402-1530 \
--prompt-file .claude/review-security.md
agent-cli dev agent review-auth \
--tmux-session review-auth-performance-20260402-1530 \
--prompt-file .claude/review-performance.md
agent-cli dev agent review-auth \
--tmux-session review-auth-tests-20260402-1530 \
--prompt-file .claude/review-tests.md
Key rules for same-worktree launches:
dev agent, not dev new, after the worktree already existsdev agent --agent <agent> to select a specific agent for an existing worktree; --with-agent remains a deprecated alias on this subcommand--tmux-session <unique-name> and use a different session name for each launch-m tmux for human-driven grouped windows or when the user explicitly wants agents to share one tmux session-m tmux joins the deterministic repo-scoped tmux session-m tmux opens a new window in the current session unless you pass --tmux-session <name>, which reuses or creates a specific tmux session and also implies When multiple agents share a worktree, explicitly assign both a focus area and a unique report file. If you rerun the same review prompt often, prefer a timestamped filename such as .claude/REPORT-security-20260319-153045-123.md.
Prompt pattern:
Review the auth module for security issues only.
When complete, write findings to .claude/REPORT-security-20260319-153045-123.md including:
- Summary
- Issues found with file/line references
- Suggested fixes
For non-interactive contexts (scripts, cron jobs, other assistants), combine --prompt-file with --tmux-session:
agent-cli dev new validation-a --from HEAD --agent codex \
--tmux-session validation-a-20260402-1530 \
--prompt-file .claude/validation-a.md
This works without an attached terminal. For autonomous or scripted launches, prefer a unique --tmux-session per agent so separate runs do not trample each other by sharing one tmux session. Use bare -m tmux only when you explicitly want shared tmux grouping. Launches may also run pre-launch preparation by default; use --no-hooks only when you explicitly need to bypass that behavior.
dev rm and dev clean also clean up tmux windows that agent-cli tagged for the worktreeIf asked to implement auth, payments, and notifications:
# Spawn three parallel agents
agent-cli dev new auth-feature --prompt "Implement JWT authentication..."
agent-cli dev new payment-integration --prompt "Add Stripe payment processing..."
agent-cli dev new email-notifications --prompt "Implement email notification system..."
Each agent works independently in its own branch. Results can be reviewed and merged separately.
| Option | Description |
|---|---|
--start-agent | Start the default/auto-detected agent without an initial prompt |
--prompt / -p | Initial prompt for the agent (short prompts only) |
--prompt-file / -P | Read prompt from file (recommended for longer prompts) |
--from / -f | Base ref (default: origin/main). Use --from HEAD when reviewing/testing current branch! |
@examples.md
-m tmux. or :.claude/REPORT-security-<run-id>.md or .claude/REPORT-tests-<run-id>.md.claude/ (e.g., TASK-{timestamp}-{hex}.md), so parallel launches do not overwrite each other--agent | Specific agent (or auto): claude, aider, codex, gemini |
--agent-args | Extra arguments for the agent |
--tmux-session | Reuse or create a specific tmux session. For autonomous agents, prefer a unique name per launch |
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.