# CTASK_SESSIONS Script Specification

## Overview

The `CTASK_SESSIONS` environment variable can point to an executable script that provides a custom list of available task sessions. When set, `ctask select` will invoke this script instead of using the default session discovery mechanism.

## Requirements

### Exit Code
- **Success**: Exit with code `0` when sessions are successfully retrieved
- **Failure**: Exit with non-zero code on error

### Output Format
The script must output valid JSON to stdout in the following format:

```json
[
  {
    "name": "session-identifier",
    "path": "/absolute/path/to/session/tasks/directory",
    "description": "Optional human-readable description"
  }
]
```

### Field Specifications

#### `name` (required, string)
- Unique identifier for the session
- Used for display in the session picker
- Should be human-readable but can be technical (e.g., UUID, slug)
- Examples: `"abc-123"`, `"my-project-session"`, `"2024-02-28-work"`

#### `path` (required, string)
- Absolute path to the directory containing task JSON files
- This directory will be used by ctask to read/write task files (e.g., `1.json`, `2.json`)
- Must be accessible by the user running ctask
- Examples: `"/home/user/.claude/tasks/abc-123"`, `"/tmp/project-tasks"`

#### `description` (optional, string)
- Human-readable description of the session
- Displayed alongside the session name in the picker
- Used to help users identify sessions
- Can be truncated for display purposes
- Examples: `"Build a CLI tool"`, `"Web scraper project - started Feb 28"`

### Example Output

#### Minimal (required fields only)
```json
[
  {
    "name": "session-1",
    "path": "/home/user/.claude/tasks/session-1"
  },
  {
    "name": "session-2",
    "path": "/home/user/.claude/tasks/session-2"
  }
]
```

#### With descriptions
```json
[
  {
    "name": "abc-123",
    "path": "/home/user/.claude/tasks/abc-123",
    "description": "Build a task management CLI tool"
  },
  {
    "name": "xyz-789",
    "path": "/home/user/projects/my-app/tasks",
    "description": "Web scraper for product data - started 2024-02-27"
  }
]
```

#### Empty list
```json
[]
```

## Display Behavior

When displayed in the session picker:
- **Without description**: Shows only the `name` (in bold)
  ```
  ? Select a session:
  ❯ session-1
    session-2
  ```

- **With description**: Shows `name - description` (name in bold, description in normal weight)
  ```
  ? Select a session:
  ❯ abc-123 - Build a task management CLI tool
    xyz-789 - Web scraper for product data - started 2024-02-27
  ```

Note: The session name is displayed in bold text to differentiate it from the description.

## Error Handling

### Invalid JSON
If the script outputs invalid JSON, ctask will display:
```
Error getting sessions: <error details>
```

### Non-zero exit code
If the script exits with a non-zero code, ctask will display:
```
Error getting sessions: <error details>
```

### Empty list
If the script returns an empty array `[]`, ctask will display:
```
No sessions available
```

## Example Implementation

### Bash Script
```bash
#!/bin/bash

# Simple example that lists sessions from a custom directory
SESSIONS_DIR="/home/user/my-sessions"

sessions='['
first=true

for session_dir in "$SESSIONS_DIR"/*; do
  if [ -d "$session_dir" ]; then
    name=$(basename "$session_dir")

    if [ "$first" = true ]; then
      first=false
    else
      sessions+=','
    fi

    sessions+="{\"name\":\"$name\",\"path\":\"$session_dir\"}"
  fi
done

sessions+=']'

echo "$sessions"
```

### Python Script
```python
#!/usr/bin/env python3
import json
from pathlib import Path

def get_sessions():
    sessions_dir = Path("/home/user/my-sessions")
    sessions = []

    for session_dir in sessions_dir.iterdir():
        if session_dir.is_dir():
            sessions.append({
                "name": session_dir.name,
                "path": str(session_dir),
                "description": f"Session {session_dir.name}"
            })

    return sessions

if __name__ == "__main__":
    sessions = get_sessions()
    print(json.dumps(sessions, indent=2))
```

## Usage

1. Create an executable script following this specification
2. Set the environment variable:
   ```bash
   export CTASK_SESSIONS=/path/to/your/script
   ```
3. Run `ctask select` to use your custom session provider

## Notes

- The script is invoked every time `ctask select` is run
- Performance: Keep the script fast (< 1 second) for good UX
- The script runs in the user's environment with their permissions
- Sorting: Order the sessions array however you prefer (e.g., by most recent, alphabetically)
- The `path` directory doesn't need to exist yet - ctask will create it when adding the first task