# session_start — Start an Async Agent in a New or Existing Session

**Script name:** `session_start`

**Script location:** [`scripts/session_start.ts`](../../../scripts/session_start.ts)

**Invoke:**
```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_start.ts \
  --tag TAG --agent AGENT (--prompt TEXT | --prompt-file PATH) \
  [--name NAME] [--restart] [--server URL]
```

**CRITICAL:** Always invoke the script using bash and the format noted above. **Never** try to use the skill as a task, or invoke it through any other method than by directly calling bash with a command of the form listed above under "Invoke:".

## Synopsis

```
session_start.ts --tag TAG --agent AGENT (--prompt TEXT | --prompt-file PATH) [OPTIONS]
```

Checks whether a session tagged `[TAG]` already exists. If it does and
`--restart` is not set, the existing session is returned without change. If the
session does not exist (or `--restart` is set), a new session is created with
title `[TAG] display-name` and the agent is launched asynchronously via
`POST /session/{id}/prompt_async` (fire-and-forget).

## Arguments

### Required

| Flag | Type | Description |
|------|------|-------------|
| `--tag TAG` | string | Session tag without brackets (e.g. `AUTO-IMP-ISSUE-42`) |
| `--agent AGENT` | string | Agent definition name to launch (e.g. `task-implementor`) |
| `--prompt TEXT` | string | Prompt text to send (suitable for short inline prompts) |
| `--prompt-file PATH` | string | Path to a file containing the prompt text — preferred for long or multi-line prompts to avoid shell-escaping issues |

Exactly one of `--prompt` or `--prompt-file` is required.

### Optional

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name NAME` | string | agent name | Display name appended after the tag: `[TAG] NAME` |
| `--restart` | flag | false | Replace any existing session with the same tag |
| `--server URL` | string | `http://localhost:4096` | OpenCode Server base URL |
| `-h`, `--help` | — | — | Print usage to stderr and exit 0 |

## Output

Written to **stdout** as a JSON object:

| Field | Type | Description |
|-------|------|-------------|
| `session_id` | string | ID of the new or existing session |
| `status` | string | `busy` (newly launched) or current status of existing session |
| `created` | boolean | `true` if a new session was created; `false` if existing was returned |
| `message` | string | Human-readable description of what happened |

Example (new session created):
```json
{
  "session_id": "ses_abc123",
  "status": "busy",
  "created": true,
  "message": "Session created and agent \"task-implementor\" launched in ses_abc123"
}
```

Example (existing session returned without change):
```json
{
  "session_id": "ses_def456",
  "status": "idle",
  "created": false,
  "message": "Existing session found: [AUTO-IMP-ISSUE-42] task-implementor [idle]"
}
```

## Diagnostics / stderr

```
Checking for existing session with tag [AUTO-IMP-ISSUE-42]…
Creating new session "[AUTO-IMP-ISSUE-42] task-implementor"…
Created session ses_abc123.
Launching agent "task-implementor" in session ses_abc123…
Agent launched (prompt_async returned 204).
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success — JSON written to stdout |
| 1 | Fatal error — missing required arg or API failure |

## Passing Long Prompts

For prompts that contain newlines, special characters, JSON, or are otherwise
difficult to inline in a shell command, use `--prompt-file`:

```bash
# 1. Write the prompt to a temp file (via the Edit tool or bash redirection):
cat > /tmp/my-prompt.txt << 'EOF'
pr_number: 42
pr_title: "Fix null pointer in login handler"
...full prompt text...
EOF

# 2. Call the script with --prompt-file:
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_start.ts \
  --tag "AUTO-PRMRG-PR-42" \
  --agent "pr-merge-worker" \
  --prompt-file /tmp/my-prompt.txt
```

## Usage Examples

```bash
# Start a new session (inline short prompt)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_start.ts \
  --tag "AUTO-IMP-ISSUE-42" \
  --agent "task-implementor" \
  --prompt "Implement issue #42. forgejo_url: https://git.cleverthis.com ..."

# Start with prompt from file (preferred for complex prompts)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_start.ts \
  --tag "AUTO-IMP-ISSUE-42" \
  --agent "task-implementor" \
  --prompt-file /tmp/issue-42-prompt.txt

# Restart an existing session (stop old one, create fresh)
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_start.ts \
  --tag "AUTO-IMP-ISSUE-42" \
  --agent "task-implementor" \
  --prompt-file /tmp/issue-42-prompt.txt \
  --restart

# Custom display name
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_start.ts \
  --tag "AUTO-SUP" \
  --agent "implementation-supervisor" \
  --name "impl-pool-supervisor" \
  --prompt "You are the implementation supervisor..."
```

## Dependencies

- Node.js ≥ 18 (native `fetch` API)
- `npx tsx` for TypeScript execution
- Zero external npm packages
