1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
# 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
|
