Task Commands

The genie task command group manages the full task lifecycle — from creation through stage transitions to completion. Tasks are stored in PostgreSQL and support priorities, dependencies, blocking, tagging, and execution locking.

`genie task create`

Create a new task.

genie task create <title> [options]

Option	Description
`--type <type>`	Task type (default: `software`)
`--priority <priority>`	Priority: `urgent`, `high`, `normal`, `low` (default: `normal`)
`--due <date>`	Due date (`YYYY-MM-DD`)
`--start <date>`	Start date (`YYYY-MM-DD`)
`--tags <tags>`	Comma-separated tag IDs
`--parent <id>`	Parent task ID or `#seq`
`--assign <name>`	Assign to local actor
`--description <text>`	Task description
`--effort <effort>`	Estimated effort (e.g., `2h`, `3 points`)
`--comment <msg>`	Initial comment on the task
`--project <name>`	Create task in a specific project (overrides CWD)
`--board <name>`	Board name to assign task to
`--gh <owner/repo#N>`	Link to a GitHub issue or PR
`--external-id <id>`	External tracker ID
`--external-url <url>`	External tracker URL

genie task create "Implement auth middleware" --type software --priority high
genie task create "Write API docs" --parent #42 --assign docs-agent

`genie task list`

List tasks with filters.

genie task list [options]

Option	Description
`--stage <stage>`	Filter by stage
`--type <type>`	Filter by type
`--status <status>`	Filter by status
`--priority <priority>`	Filter by priority
`--release <release>`	Filter by release
`--due-before <date>`	Filter by due date
`--mine`	Show only tasks assigned to me
`--project <name>`	Show tasks for a specific project
`--board <name>`	Filter by board name
`--by-column`	Group tasks by board column (Kanban view)
`--include-done`	Include done tasks in Kanban view (hidden by default)
`--all`	Show tasks from ALL projects
`--gh <owner/repo>`	Filter by linked GitHub repo
`--limit <n>`	Max rows returned
`--offset <n>`	Skip first N rows (pagination)
`--json`	Output as JSON

genie task list --stage build --priority high
genie task list --mine --by-column
genie task list --all --json

`genie task show`

Show task detail. Accepts task UUID or #seq shorthand.

genie task show <id> [--json]

`genie task move`

Move a task to a new stage in its pipeline.

genie task move <id> --to <stage> [--comment <msg>]

Stages follow the task type’s pipeline. For the default software type:

draft → brainstorm → wish → build → review → qa → ship

genie task move #42 --to build --comment "Wish approved, dispatching engineers"
genie task move #42 --to review --comment "Implementation complete"

`genie task assign`

Assign an actor to a task.

genie task assign <id> --to <name> [--role <role>] [--comment <msg>]

Option	Description
`--to <name>`	Actor name
`--role <role>`	Actor role (default: `assignee`)
`--comment <msg>`	Comment on the assignment

`genie task tag`

Add tags to a task.

genie task tag <id> <tags...>

`genie task comment`

Add a comment to a task. Comments are used by skills to log progress, trace findings, and fix attempts.

genie task comment <id> <message> [--reply-to <msg-id>]

genie task comment #42 "Building group 1..."
genie task comment #42 "Root cause: missing null check in auth.ts:142"

`genie task block`

Mark a task as blocked with a reason.

genie task block <id> --reason <reason> [--comment <msg>]

genie task block #42 --reason "Waiting for API spec from design team"
genie task block #42 --reason "Fix loop exceeded (2/2)"

`genie task unblock`

Unblock a task.

genie task unblock <id> [--comment <msg>]

`genie task done`

Mark a task as done. This sets the task status to done — it does not move the task to a stage.

genie task done <id> [--comment <msg>]

genie task done is a status change, not a stage move. It is separate from genie task move --to ship. Use done when the task is fully complete. Use move to advance through pipeline stages.

genie task done #42 --comment "PR #123 merged to dev"

`genie task checkout`

Atomically claim a task for execution. Prevents two agents from working on the same task simultaneously.

genie task checkout <id>

The lock is stored as checkout_run_id on the task with an execution_locked_at timestamp. Locks expire after 10 minutes by default.

`genie task release`

Release a task checkout claim after work is complete.

genie task release <id>

`genie task unlock`

Force-release a stale checkout. Admin override for when a lock wasn’t properly released (e.g., crashed agent).

genie task unlock <id>

`genie task dep`

Manage task dependencies. Supports three relationship types.

genie task dep <id> [options]

Option	Description
`--depends-on <id2>`	This task depends on `id2`
`--blocks <id2>`	This task blocks `id2`
`--relates-to <id2>`	This task relates to `id2`
`--remove <id2>`	Remove dependency on `id2`

genie task dep #42 --depends-on #41
genie task dep #42 --blocks #43
genie task dep #42 --remove #41

`genie task link`

Link a task to an external tracker (GitHub, Jira, etc.).

genie task link <id> [options]

Option	Description
`--gh <owner/repo#N>`	Link to a GitHub issue or PR
`--external-id <id>`	External tracker ID
`--external-url <url>`	External tracker URL

genie task link #42 --gh automagik-dev/genie#123
genie task link #42 --external-url https://linear.app/team/ENG-456 --external-id ENG-456

`genie task close-merged`

Auto-close tasks whose wish slugs match recently merged PRs.

genie task close-merged [options]

Option	Description
`--since <duration>`	Time window for merged PRs (e.g., `24h`, `7d`)
`--dry-run`	Show what would be closed without making changes
`--repo <owner/repo>`	GitHub repo to scan (default: current repo)

$ genie task close-merged
Scanning merged PRs...
  ✅ #42 "Add OAuth" — PR #123 merged, closing
  ✅ #45 "Fix token refresh" — PR #127 merged, closing
  2 tasks closed.

`genie task archive`

Archive a task (soft-delete — preserves all data).

genie task archive <id>

genie task archive #42

`genie task unarchive`

Restore an archived task to its previous status.

genie task unarchive <id>

genie task unarchive #42

Task ID Formats

Tasks can be referenced by UUID or sequence number:

Format	Scope	Example
UUID	Global	`task-6c3a2cf2`
`#seq`	Current repo	`#42`
`project#seq`	Display only	`my-project#42`

The #seq shorthand resolves based on the current working directory’s repo. For cross-worktree operations, always use the full UUID.

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Tasks

Task Commands

`genie task create`

`genie task list`

`genie task show`

`genie task move`

`genie task assign`

`genie task tag`

`genie task comment`

`genie task block`

`genie task unblock`

`genie task done`

`genie task checkout`

`genie task release`

`genie task unlock`

`genie task dep`

`genie task link`

`genie task close-merged`

`genie task archive`

`genie task unarchive`

Task ID Formats

​Task Commands

​genie task create

​genie task list

​genie task show

​genie task move

​genie task assign

​genie task tag

​genie task comment

​genie task block

​genie task unblock

​genie task done

​genie task checkout

​genie task release

​genie task unlock

​genie task dep

​genie task link

​genie task close-merged

​genie task archive

​genie task unarchive

​Task ID Formats

Task Commands

`genie task create`

`genie task list`

`genie task show`

`genie task move`

`genie task assign`

`genie task tag`

`genie task comment`

`genie task block`

`genie task unblock`

`genie task done`

`genie task checkout`

`genie task release`

`genie task unlock`

`genie task dep`

`genie task link`

`genie task close-merged`

`genie task archive`

`genie task unarchive`

Task ID Formats