cli-agent-runner

What this skill does

# CLI Agent Runner Skill

## Intro

This skill provides guidance on using the `cli-agent-runner.sh` script to delegate work to Claude Code sessions.

Use this when you need to:
- Delegate a task to a specialized session for long-running operations
- Resume tasks later using a simple session name (no session ID management needed)
- Run sessions in the background with polling support
- Get clean result output without manual JSON parsing
- Optionally use agent definitions for specialized behavior

**Key Benefits:**
- Session names instead of session IDs (simpler to track and resume)
- Automatic session file management in `.cli-agent-runner/agent-sessions/` directory
- Built-in result extraction (no need for head/tail/jq commands)
- Clean output to stdout, errors to stderr
- Optional agent associations for specialized capabilities

## Terminology

- **Session**: A named, running conversation with Claude Code
- **Agent**: A reusable configuration/definition that provides specialized behavior for sessions
- **Session Name**: The unique identifier you give to a conversation (e.g., `architect`, `reviewer`)
- **Agent Name**: The identifier for a reusable agent definition (e.g., `system-architect`, `security-reviewer`)

## Variables

The following variables are used in the commands and instructions:

- `<session-name>`: A unique identifier for the session (alphanumeric, dash, underscore only; max 30 chars)
- `<agent-name>`: Optional agent definition to use for the session
- `<initial-prompt>`: The prompt or task description for a new session
- `<resume-prompt>`: The prompt or task description to continue an existing session's work
- `<POLL_INTERVAL>`: The interval in seconds to wait between polling attempts. Default is 60 seconds.

## Script Location

**IMPORTANT:** The `cli-agent-runner.sh` script is located in the same directory as this SKILL.md file.
So it is in the root folder of the skill plugin.

Before using the script for the first time in a conversation, you MUST locate it:

1. Identify the root folder of the plugin skill and append the script name:
   ```
   <path-to-skill-root-folder>/cli-agent-runner.sh
   ```
2. Store this path mentally for the rest of the conversation: <absolute-path-to-cli-agent-runner.sh>
3. Use the absolute path in all subsequent commands

**Example:**
```bash
# Use that exact path in all commands:
<absolute-path-to-cli-agent-runner.sh> new <session-name> -p "<prompt>"
```

**Note:** In all examples below, `cli-agent-runner.sh` represents the absolute path <absolute-path-to-cli-agent-runner.sh> you discovered. Replace it with the actual path when executing commands.

## Commands Overview

The cli-agent-runner.sh supports five commands:

1. **new** - Create a new session (optionally with an agent)
2. **resume** - Resume an existing session by name
3. **list** - List all sessions with their session IDs
4. **list-agents** - List all available agent definitions
5. **clean** - Remove all sessions

## Usage Patterns

### Pattern 1: Synchronous Execution (Wait for Completion)

Use this when you want to wait for the session to complete and get the result immediately.

**Creating a new session:**
```bash
./cli-agent-runner.sh new <session-name> -p "<initial-prompt>"
```

**Creating a new session with an agent:**
```bash
./cli-agent-runner.sh new <session-name> --agent <agent-name> -p "<initial-prompt>"
```

**Creating a new session with prompt from file/stdin:**

This should be considered when the prompt is large or complex or already a prompt file exists potentially created by another session.

```bash
cat prompt.md | ./cli-agent-runner.sh new <session-name>
```

**Resuming an existing session:**
```bash
./cli-agent-runner.sh resume <session-name> -p "<resume-prompt>"
```

**Example:**
```bash
# Create new session with agent
./cli-agent-runner.sh new architect --agent system-architect -p "Create a high-level architecture document for a user authentication system"

# The script blocks until completion and outputs the result
# Output: <result from session>

# Resume the session later (agent association is remembered)
./cli-agent-runner.sh resume architect -p "Add API endpoint specifications to the architecture"
```

### Pattern 2: Background Execution with Polling

Use this when you want to start the session in the background and poll for completion.

**Instructions:**

**1. Start the session in the background:**
- Use Bash tool with `run_in_background: true`
- Use either `new` or `resume` command
- **Important:** Note the bash_id returned by the Bash tool

**Example for new session:**
```bash
./cli-agent-runner.sh new <session-name> -p "<initial-prompt>"
```

**Example for new session with agent:**
```bash
./cli-agent-runner.sh new <session-name> --agent <agent-name> -p "<initial-prompt>"
```

**Example for resuming session:**
```bash
./cli-agent-runner.sh resume <session-name> -p "<resume-prompt>"
```

**2. Initial Polling Wait:**
- Use Bash tool (NOT background): `sleep <POLL_INTERVAL>`
- Default POLL_INTERVAL is 60 seconds

**3. Check if background process is still running:**
- Use BashOutput tool with the bash_id from step 1
- The tool returns shell status showing if process is running or completed
- If status shows still running: continue to step 4
- If status shows completed: continue to step 5
- **Do NOT use:** kill -0, pgrep, ps, or any other process checking commands

**4. Polling Wait Loop:**
- Use Bash tool (NOT background): `sleep <POLL_INTERVAL>`
- Return to step 3

**5. Process Completed - Get Results:**
- The result is already captured in the Bash tool's output when the process completes
- Simply read the output from the completed Bash execution
- The output will be the session's result (already extracted by the script)

**Full Background Example:**
```bash
# Step 1: Start in background
./cli-agent-runner.sh new architect --agent system-architect -p "Design authentication system"
# Returns bash_id: abc123

# Step 2: Initial wait
sleep 60

# Step 3: Check status
# Use BashOutput with bash_id: abc123
# If status: running, continue to step 4
# If status: completed, read the output - it contains the result

# Step 4: If still running, wait and check again
sleep 60
# Return to step 3
```

### Pattern 3: Listing Sessions

Use this to see all existing sessions and their status.

```bash
./cli-agent-runner.sh list
```

**Output format:**
```
session-name (session: session-id)
architect (session: 3db5dca9-6829-4cb7-a645-c64dbd98244d)
reviewer (session: initializing)
```

- "initializing" means the session file exists but hasn't started yet (empty file)
- "unknown" means the session ID couldn't be extracted
- Otherwise, shows the actual session ID

### Pattern 4: Listing Available Agent Definitions

Use this to discover what agent definitions are available before creating a session.

```bash
./cli-agent-runner.sh list-agents
```

**Output format:**
```
agent-name:
description

---

next-agent-name:
description

---

another-agent-name:
description
```

**Example output:**
```
code-reviewer:
Reviews code for best practices, bugs, and potential improvements

---

documentation-writer:
Creates comprehensive technical documentation and guides

---

system-architect:
Expert in designing scalable system architectures
```

**Use Case:**
- Discover available agents before creating a new session
- Understand what specialized capabilities are available
- Choose the appropriate agent for your task

**Important Notes:**
- Each agent definition is separated by `---` for clear parsing
- Agent names can be used with `--agent` flag when creating sessions
- If no agents exist, outputs: "No agent definitions found"

### Pattern 5: Cleaning All Sessions

Use this to remove all sessions and start fresh.

```bash
./cli-agent-runner.sh clean
```

**Behavior:**
- Removes the entire `.cli-agent-runner/agent-sessions/` directory
- All session files and history are permanently deleted
- No confirmation prompt - immediate deletion
- Safe to run even if n