# 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`.