---
name: spawn-terminal
description: "Spawn a new terminal window to run CLI commands (ffmpeg, curl, python, etc.). Use for non-AI command execution."
---

# 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

| Variable | Default | Description |
|----------|---------|-------------|
| LOG_TO_FILE | false | Write full terminal output to debug file |
| CAPTURE | false | Block and return output directly |

## 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`:

```python
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"