ctask - Claude Task Manager

CLI tool for managing Claude-generated tasks.

Installation

Quick Install

cd claude-task
./install.sh

Then add to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Manual Installation

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:

{
  "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 for specification and examples/ for sample implementations.
• EDITOR: Editor to use for ctask edit (default: vi)

Usage

First, select a session:

ctask select

This displays available sessions and lets you choose one. The selection persists for your terminal session.

List tasks (default action)

ctask
ctask list
ctask ls      # alias for list

Shows a tabular view of all tasks in the selected session directory.

Create a task

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

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

ctask edit 8

Opens the task JSON file in your $EDITOR.

Delete a task

ctask delete 8
ctask rm 8     # alias for delete

Deletes the specified task file.

Select a session

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 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:

{
  "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.