Purpose

Spawn a new terminal window to execute CLI commands. This skill is for generic command execution, NOT for spawning AI agents. For AI agents, use the spawn:agent skill instead.

Variables

Instructions

MANDATORY - You MUST follow the Workflow steps below in order. Do not skip steps.

1. •Identify the CLI command the user wants to run
2. •Run <command> --help first to verify syntax and options
3. •Execute the command in a new terminal using fork_terminal()

Red Flags - STOP and follow Cookbook

If you're about to:

• •Execute a command without checking its --help first
• •Assume you know the command syntax
• •Skip the --help step "because it's simple"
• •Spawn an AI agent (use spawn:agent instead)

STOP -> Run <command> --help first -> Review output -> Then proceed

Workflow

MANDATORY CHECKPOINTS - Verify each before proceeding:

1. • Understand the user's request
2. • VERIFY: This is a CLI command, NOT an AI agent request
3. • READ: '../agent/fork_terminal.py' to understand the tooling
4. • Follow the Cookbook: Read './cookbook/cli-command.md'
5. • CHECKPOINT: Ran <command> --help and reviewed options
6. • Execute fork_terminal(command, log_to_file=False, log_agent_output=False)

Cookbook

CLI Commands

• •IF: User requests any non-AI CLI command (ffmpeg, curl, python, npm, etc.)
• •THEN: Read and execute './cookbook/cli-command.md'
• •Examples:
  • •"Create a new terminal to run ffmpeg"
  • •"Spawn terminal with curl"
  • •"Fork a terminal to run python script.py"
  • •"New terminal: npm run build"

Usage

The fork_terminal() function is located at ../agent/fork_terminal.py:

from spawn.agent.fork_terminal import fork_terminal

# Simple command execution (no output capture)
fork_terminal("npm run build")

# With debug output capture
file_path = fork_terminal("ffmpeg -i video.mp4 output.gif", log_to_file=True)

# Blocking capture (waits for completion)
output = fork_terminal("python script.py", capture=True, log_to_file=True)

When to Use spawn:agent Instead

If the user mentions any of these, use spawn:agent:

• •Claude, Claude Code
• •Codex, OpenAI
• •Gemini, Google
• •Cursor
• •OpenCode
• •Copilot, GitHub Copilot
• •"AI agent", "coding agent", "spawn agent"