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
|
# ctask - Claude Task Manager
CLI tool for managing Claude-generated tasks.
## Installation
### Quick Install
```bash
cd claude-task
./install.sh
```
Then add to your `~/.bashrc` or `~/.zshrc`:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
### Manual Installation
```bash
cd claude-task
uv sync
ln -s $(pwd)/.venv/bin/ctask ~/.local/bin/ctask
```
## Directory Structure
Tasks are organized by session in `~/.claude/tasks/`:
```
~/.claude/
├── tasks/
│ ├── abc-123-session-id/ (session directory)
│ │ ├── 1.json
│ │ ├── 2.json
│ │ └── 3.json
│ └── xyz-789-session-id/ (another session)
│ └── 1.json
└── projects/
└── my-project/
└── sessions-index.json (session metadata)
```
The `sessions-index.json` contains session metadata including `firstPrompt` which is used as the session description:
```json
{
"version": 1,
"entries": [
{
"sessionId": "abc-123-session-id",
"firstPrompt": "Build a CLI tool for task management",
"messageCount": 5,
"created": "2026-02-28T10:00:00Z"
}
]
}
```
**Important:** You must select a session with `ctask select` before using other commands.
## Configuration
- `CTASK_SESSIONS`: Optional path to custom session listing script. See [CTASK_SESSIONS_SPEC.md](CTASK_SESSIONS_SPEC.md) for specification and [examples/](examples/) for sample implementations.
- `EDITOR`: Editor to use for `ctask edit` (default: `vi`)
## Usage
**First, select a session:**
```bash
ctask select
```
This displays available sessions and lets you choose one. The selection persists for your terminal session.
### List tasks (default action)
```bash
ctask
ctask list
ctask ls # alias for list
```
Shows a tabular view of all tasks in the selected session directory.
### Create a task
```bash
ctask create "Task name" "Task description"
ctask add "Task name" "Task description" # alias for create
ctask create "Fix bug" "Fix authentication bug" --status pending --active-form "Fixing bug"
ctask create "Deploy" --after 5 --after 6 # this task comes after tasks 5 and 6
ctask create "Write code" --before 10 # this task comes before task 10
```
Options:
- `--status`: Task status (default: `pending`)
- `--active-form`: Active form description
- `--blocks` / `--before`: Task IDs this task blocks (this comes before them)
- `--blocked-by` / `--after`: Task IDs blocking this task (this comes after them)
### Modify a task
```bash
ctask mod 8 --status in_progress
ctask mod 8 --name "New name" --description "New description"
ctask mod 8 --after 5 # add dependency
ctask mod 8 --unblock # remove all blockers
ctask mod 8 --unblock --after 5 # replace blockers with only task 5
```
Options:
- `--name`: Update task name
- `--description`: Update description
- `--status`: Update status
- `--active-form`: Update active form
- `--blocks` / `--before`: Set task IDs this blocks (replaces existing)
- `--blocked-by` / `--after`: Set/add task IDs blocking this (adds to existing, or replaces if used with --unblock)
- `--unblock`: Clear all blockers before applying --blocked-by
### Edit a task
```bash
ctask edit 8
```
Opens the task JSON file in your `$EDITOR`.
### Delete a task
```bash
ctask delete 8
ctask rm 8 # alias for delete
```
Deletes the specified task file.
### Select a session
```bash
ctask select
```
Displays available sessions from `~/.claude/tasks/` (sorted by most recently used) with an interactive picker. Sessions show their `firstPrompt` from the sessions index as descriptions. The selection is stored per-terminal-session using the session leader PID.
You can optionally set `CTASK_SESSIONS` to point to a custom script that returns a JSON array of sessions. See [CTASK_SESSIONS_SPEC.md](CTASK_SESSIONS_SPEC.md) for the complete specification.
**Note:** All other commands require a session to be selected first. If you haven't selected a session, you'll see:
```
No session selected. Run 'ctask select' first.
```
## Task Format
Tasks are stored as JSON files with numerically increasing IDs:
```json
{
"id": "7",
"subject": "Task title",
"description": "Detailed description",
"activeForm": "Present continuous form",
"status": "pending",
"blocks": [],
"blockedBy": []
}
```
Task IDs are automatically incremented when creating new tasks. The ID is determined by:
- The maximum of existing task IDs + 1
- The value in `.highwatermark` file + 1 (if it exists)
The `.highwatermark` file in each session directory is managed by Claude and tracks the highest task ID to prevent ID conflicts.
## Session State
ctask maintains session state using the session leader PID. Each terminal session can have its own active task directory selected via `ctask select`.
Session state is stored in `~/.claude/ctask_state.json`.
|
