itinerary 0.1.0

CLI for managing Claude Code tasks
Documentation

Itinerary

A command-line interface for managing Claude Code tasks.

Itinerary provides task discovery, querying, modification, and workflow operations optimized for AI agent coordination. Tasks use Claude Code's stnadard JSON file format in ~/.claude/tasks/<task_list_id>/.

Installation

cargo install itinerary

Quick Start

By default, Itinerary uses the CLAUDE_CODE_TASK_LIST_ID environment variable or the current directory name as the task list ID. From any project directory, you can immediately start managing tasks:

Create a task:

it create "Fix login bug" --body "The login form rejects valid passwords"

Show tasks ready to work on:

it ready

View task details:

it show 1

Add a dependency (task 5 depends on task 3):

it dep add 5 3

Mark a task complete:

it close 1

Command Reference

Task Operations

Command Description
show <id> Display detailed task information
create <subject> Create a new task
update <id> Modify an existing task
close <id> Mark tasks as completed
reopen <id> Revert completed tasks to pending
edit <id> Open task in $EDITOR

Querying

Command Description
list Query and display tasks with filtering
ready Show tasks ready to work on
blocked Show tasks blocked by dependencies
search <query> Search tasks by subject and description
tree Display tasks in dependency hierarchy
graph <id> Display ASCII dependency graph
count Count tasks matching filters
status Show summary statistics

Workflow

Command Description
pop Atomic ready + claim + show for task acquisition
claim <id> Mark task as in-progress
q <subject> Quick capture: create task and output ID
duplicate <id> <canonical> Mark task as duplicate of another

Organization

Command Description
dep Manage task dependencies
label Manage task labels
category Manage task categories

Data Management

Command Description
export Export tasks to JSON Lines format
import Import tasks from JSON Lines format
doctor Health checks and repairs
completion Generate shell completions

Global Options

--json                Output structured JSON
-v, --verbose         Enable detailed logging
-q, --quiet           Suppress non-essential output
--task-list <id>      Specify task list ID
--tasks-root <path>   Override tasks root directory
--readonly            Block write operations

Environment Variables

Variable Description
CLAUDE_CODE_TASK_LIST_ID Override task list ID (takes precedence over current directory)
ITINERARY_TASK_LIST Alternative task list ID
ITINERARY_TASKS_ROOT Override tasks root directory (default: ~/.claude/tasks)

Task List Resolution Order:

  1. --task-list CLI flag
  2. CLAUDE_CODE_TASK_LIST_ID environment variable
  3. ITINERARY_TASK_LIST environment variable
  4. Current directory name (default)

Task Status

Tasks have a status field with one of three values:

Status Description
pending Ready to work on
in_progress Currently being worked on
completed Finished

Examples

Filter tasks by status and priority

it list --status pending --priority-max 1

Find tasks with a label

it list --label urgent

Search task descriptions

it search "authentication"

Export and import

it export -o backup.jsonl
it import backup.jsonl

Generate shell completions

it completion bash > ~/.bash_completion.d/itinerary
it completion zsh > ~/.zfunc/_itinerary

Task Metadata

Itinerary extends Claude Code tasks with custom metadata fields stored in the task's metadata object:

Field Type Description
priority Integer 0-4 Task priority where 0 is highest. Priority 4 is treated as backlog and excluded from ready by default.
labels Array of strings Arbitrary tags for categorizing tasks (e.g., ["urgent", "frontend"])
category String Single category for grouping related tasks (e.g., "api", "ui")

These fields can be set when creating tasks:

it create "Fix bug" --priority 1 --label urgent --category api

And used for filtering:

it list --priority 0 --label urgent --category api

Documentation

For detailed design documentation, see docs/itinerary_design.md.

License

Apache-2.0