task

The istok task command group provides direct access to tasks in the current Istok project.

Tasks use project-scoped numeric IDs in the CLI. For example, #12 identifies task 12 inside the current project.

Commands

istok task --help

The available task commands are:

Create a task

Create a task with a title:

istok task create --title "Fix authentication timeout"

You can provide additional task details:

istok task create \
  --title "Fix authentication timeout" \
  --description "Requests sometimes time out during token refresh." \
  --acceptance-criteria "Authentication requests complete without unexpected timeouts." \
  --notes "Check the refresh-token path first."

--title is required.

The other fields are optional:

For normal agent workflows, the coding agent can create tasks through MCP when non-trivial work needs to be tracked.

List tasks

List active tasks in the current project:

istok task list

The human-readable output includes:

#   STATE         TITLE                         BLOCKED BY
12  READY         Fix authentication timeout   —
13  BLOCKED       Update session handling       #12
14  IN PROGRESS   Refactor token validation     —

The displayed state describes the task’s current working state:

• READY — the task can be claimed;
• BLOCKED — an active dependency prevents it from being ready;
• IN PROGRESS — the task has an active run.

task list focuses on active work. Completed tasks are not included in the normal list.

Use a status filter when needed:

istok task list --status open

Inspect the installed command for the available filter values:

istok task list --help

Show a task

Inspect a task by its project-scoped number:

istok task show 12

The task view can include:

• title;
• description;
• acceptance criteria;
• notes;
• current derived state;
• blockers;
• dependents;
• revision;
• event history.

Unlike the normal task list, show can also be used to inspect a completed task.

The command does not modify task state.

Ready tasks

List tasks that can currently be claimed:

istok task ready

A task is ready when it is open, has no active blockers, and is not owned by a live active run.

This is useful when choosing the next piece of work to start.

Agents can use the same readiness information through MCP when selecting work automatically.

Comments

Add information to the task history:

istok task comment 12 --body "Waiting for API review."

Comments are useful for information that should remain attached to the task without representing a progress update.

For example:

• additional observations;
• clarification from a reviewer;
• handoff notes;
• information relevant to later work.

Progress

Record meaningful progress:

istok task progress 12 --body "Token refresh path updated; integration tests remain."

Progress entries are intended for significant changes in the state of the work.

Useful progress updates include:

• a major implementation step was completed;
• an important decision was made;
• a new blocker was discovered;
• validation revealed additional work;
• the task is ready for another agent to continue.

You do not need to record every small implementation step.

Dependencies

A task can be blocked by another task in the same project.

For example, make task 12 depend on task 11:

istok task dependency add 12 --blocker 11

Task 12 will remain blocked while the dependency is active.

Remove the dependency with:

istok task dependency remove 12 --blocker 11

Both task numbers are scoped to the current project.

Dependencies allow Istok and connected agents to distinguish work that is ready from work that must wait for another task.

Claim a task

Claim a ready task before starting implementation:

istok task claim 12

Claiming a task starts an active run for the work and captures the context associated with that attempt.

The result provides the run information required for subsequent run operations, including the active lease.

Conceptually:

Task #12
   ↓
claim
   ↓
Context snapshot
   +
Active run
   +
Lease

Repository retrieval is included in the normal claim workflow so the run starts with relevant project and repository context.

For exceptional cases, retrieval can be bypassed explicitly:

istok task claim 12 \
  --without-retrieval \
  --override-reason "Repository index is being repaired"

Skipping retrieval requires a reason so the exception remains part of the recorded workflow.

Active and expired runs

A task cannot normally be claimed while it already has a live active run.

If the previous run is no longer active because its lease expired, the task can become ready again. A new claim can then start a fresh run and context snapshot for the next attempt.

This allows interrupted work to continue without requiring the task itself to be recreated.

For direct run inspection and recovery commands, see run.

Task revisions

Tasks use revisions to protect state-changing operations from stale writes.

The current revision is visible when you inspect a task:

istok task show 12

Commands that require an expected revision verify that the task has not changed since you last read it.

If another operation changes the task first, read the task again and use its latest revision.

This is particularly important when completing a task.

Complete a task

After the work has been implemented and validated, complete it with the current task revision and its validation evidence:

istok task done 12 \
  --expected-revision 7 \
  --run-id 019... \
  --validation-id 019... \
  --note "Authentication timeout fixed and tests passed."

The important inputs are:

The normal completion workflow is:

Task
  ↓
Claim
  ↓
Run
  ↓
Implementation
  ↓
Validation
  ↓
Run completed
  ↓
Task done

Completion with validation evidence preserves not only the fact that the task was marked done, but also how the completed work was checked.

When evidence genuinely cannot be recorded, completion can be explicitly overridden with a reason. This should be treated as an exception rather than the normal workflow.

JSON output

Task commands support structured JSON where available:

istok task list --json

istok task show 12 --json

JSON output uses versioned schemas and project-scoped task numbers alongside canonical task identity.

See JSON output for details.

Command help

Use the built-in help for exact arguments and flags supported by your installed version:

istok task create --help
istok task list --help
istok task claim --help
istok task done --help

Next

Continue with the run command reference to learn how to inspect runs, execute commands, record validation, and finish an attempt.