istok

istok task

Create, list, show, comment on, claim, and complete tasks, and manage their dependencies.

istok task works with tasks in the current project. For what tasks and runs are and how they relate, see Tasks and runs.

Tasks have project-scoped numbers in the CLI: #12 is task 12 of the current project.

Commands

Command Purpose
create Create a task in the current project.
list List active tasks.
show ID Show a task and its history.
ready List tasks that are ready to be claimed.
comment ID Add a comment to a task.
progress ID Record meaningful progress.
dependency add TASK Add a blocking dependency.
dependency remove TASK Remove a blocking dependency.
claim ID Claim a ready task and start a run.
done ID Complete a task.

All task commands accept --json and --database PATH.

Create a task

istok task create \
  --title "Return 404 for missing orders" \
  --description "GET /orders/{id} returns 500 when the order does not exist." \
  --acceptance-criteria "Missing orders return 404 with an error body." \
  --notes "Check the repository error mapping first."
Flag Purpose
--title Required. Task title.
--description What needs to be done.
--acceptance-criteria How completion can be evaluated.
--notes Additional information.

List tasks

istok task list
#    STATE         TITLE                            BLOCKED BY
#12  READY         Return 404 for missing orders    —
#13  BLOCKED       Add order audit log              #12
#14  IN PROGRESS   Paginate order history           —

The BLOCKED BY column appears only when at least one listed task has an active blocker.

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

Completed tasks are not listed by default. Filter by status with open, blocked, or done; the flag can be repeated:

istok task list --status done
istok task list --status open --status blocked

Show a task

istok task show 12

Shows the title, description, acceptance criteria, notes, derived state, blockers, dependents, revision, and event history. It also works for completed tasks and does not change anything.

Ready tasks

istok task ready

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

Comments and progress

istok task comment 12 --body "Waiting for API review."
istok task progress 12 --body "Error mapping updated; integration tests remain."

Use comments for observations, reviewer clarifications, and notes for later work. Use progress for significant changes in the state of the work: a finished step, a decision, a new blocker, validation that revealed more work, or the task being ready for another agent.

Dependencies

Make task 13 wait for task 12:

istok task dependency add 13 --blocker 12

Remove it:

istok task dependency remove 13 --blocker 12

Both numbers refer to tasks in the current project. Task 13 stays blocked while the dependency is active.

Claim a task

istok task claim 12

Claiming starts an active run, stores a context snapshot for it, and returns the run with its lease, which later run commands need. A task with a live active run cannot be claimed. If that run’s lease has expired, the claim closes it as abandoned and starts a new attempt.

The claim refreshes the code index and includes code retrieval. To skip retrieval in an exceptional case, give a reason:

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

Context options

What a claim delivers, and the budgets it uses, are explained in Context and knowledge. To see it in advance, use istok context preview.

Flag Purpose
--context-id ID Include a specific context record, for example one with manual delivery. Can be repeated.
--context-limit N Set the durable record limit explicitly (1–64). An explicit limit is never expanded automatically.
--all-context Include all active context without the durable budget. Requires --context-override-reason.

--all-context is a legacy escape hatch; its reason is recorded with the snapshot.

If the required always context does not fit into the budget, the claim fails without creating a run and the error names the records involved. Run istok context doctor to find the cause.

Other claim options

Flag Purpose
--base-branch, --base-commit The Git branch and commit the run started from. Detected from the worktree when omitted.
--run-id, --snapshot-id Client-generated UUIDv7 IDs for integrations. Generated by Istok when omitted.

Complete a task

After the work is implemented and validated:

istok task done 12 \
  --expected-revision 7 \
  --run-id 019... \
  --validation-id 019... \
  --note "Missing orders return 404; tests pass."
Flag Purpose
--expected-revision Required. The current task revision.
--note Required. Completion note.
--run-id The succeeded run that did the work.
--validation-id A passed validation from that run.
--override-reason Complete without evidence, with an audited reason. Use only when evidence genuinely cannot be recorded.
--completion-id Client-generated UUIDv7 completion ID.

See Validation for how evidence is produced.

Revisions

State-changing commands that take --expected-revision fail if the task changed since you read it. Run istok task show 12 again and use the latest revision.

JSON output

istok task list --json
istok task show 12 --json

JSON output includes both the project-scoped number and the canonical task UUID. See JSON output.

Help

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