# session_list — List All OpenCode Sessions With Their Statuses

**Script name:** `session_list`

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

**Invoke:**
```bash
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_list.ts \
  [--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_list.ts [--server URL]
```

Fetches all sessions from the OpenCode Server and enriches each one with
its current `busy`/`idle` status and last-activity timestamp. Results are
sorted by `last_active` descending (most recently active first).

## Arguments

All arguments are optional.

| Flag | Type | Description |
|------|------|-------------|
| `--server URL` | string | OpenCode Server base URL (default: `http://localhost:4096`) |
| `-h`, `--help` | — | Print usage to stderr and exit 0 |

## Output

Written to **stdout** as a pretty-printed JSON array. Each element is a
`SessionWithStatus` object:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Session ID (e.g. `ses_abc123`) |
| `title` | string | Full session title (e.g. `[AUTO-IMP-001] implementor-worker`) |
| `tag` | string \| null | Extracted `[TAG]` portion, or `null` for untagged sessions |
| `status` | string | `busy` or `idle` |
| `last_active` | number | Epoch ms of last session update |

An **empty array** `[]` means no sessions exist on the server.

## Diagnostics / stderr

```
Fetching sessions from http://localhost:4096…
Found 5 session(s).
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success — JSON array written to stdout |
| 1 | Fatal error — message written to stderr |

## When to Use This Script

Use `session_list` when you need a complete snapshot of all active sessions,
e.g. to audit the current state of the system, discover orphaned sessions, or
identify sessions before performing bulk operations.

## Usage Examples

```bash
# List all sessions
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_list.ts

# Count total sessions
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_list.ts \
  | jq 'length'

# List only busy sessions
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_list.ts \
  | jq '[.[] | select(.status == "busy")]'

# Get all session IDs
npx --yes tsx /app/.opencode/skills/auto-agents-system/scripts/session_list.ts \
  | jq '[.[].id]'
```

## Dependencies

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