Skip to content
APX

Tasks

APX has a per-project TODO list backed by an append-only event log. Tasks are scoped to a project, addressable by short-id prefix, and never truly deleted — state transitions (done, drop) are recorded as events and the task persists forever.

Storage

Section titled “Storage”

Tasks live in ~/.apx/projects/<apxId>/tasks/YYYY-MM.jsonl, one file per month. State is the fold of the event stream: creating, completing, dropping, reopening, and patching all append events. Do not grep the JSONL directly for state — use apx task list or the API.

apx task add

Section titled “apx task add”
Terminal window
apx task add "<title>" \
  [--project <name|id|path>] \
  [--body <text>] \
  [--tag <name>]... \
  [--due <YYYY-MM-DD>] \
  [--agent <slug>] \
  [--source <label>]

--tag is repeatable. Examples:

Terminal window
apx task add "Review PR #42" --project myapp --agent reviewer --tag review
apx task add "Release notes" --project myapp --tag release --tag docs --due 2026-06-01
apx task add "Call client"   --project myapp --due 2026-05-31 --tag urgent

apx task list

Section titled “apx task list”
Terminal window
apx task list \
  [--state open|done|dropped|all] \   # default: open
  [--tag <name>] \
  [--agent <slug>] \
  [--due-before <iso>] \
  [--limit <N>] \
  [--project <name|id|path>]
Terminal window
apx task list --project myapp                          # open tasks
apx task list --project myapp --state all
apx task list --project myapp --state done
apx task list --project myapp --tag urgent
apx task list --project myapp --due-before 2026-06-01
apx task list --project myapp --agent reviewer --limit 10
apx 
$ apx task list --project myapp
ID    STATE    DUE         TAGS                TITLE
t-1a  open     2026-06-16  checkout,urgent     Wire Stripe webhooks before merge
t-2b  open     2026-06-18  tests               Retry-guard the flaky cart-total test
t-3c  open     —           docs                Document the pairing flow for the web panel
t-4d  open     2026-06-20  infra               Backfill ingestion CLI flag
apx task list — open tasks with id, title, tags, due date, and agent

apx task show

Section titled “apx task show”
Terminal window
apx task show <id> [--project <name|id|path>]
apx task show abc  [--project <name|id|path>]   # prefix match (≥ 3 chars, must be unique)

Prints the full task as JSON, including all fields and current state.

State transitions

Section titled “State transitions”
Terminal window
apx task done   <id> [--project P] [--by <name>]   # mark completed
apx task drop   <id> [--project P]                  # archive (no longer needed)
apx task reopen <id> [--project P]                  # flip back to open

done means “I completed this work.” drop means “this is no longer needed.” Metrics and reporting distinguish them — use the right one.

apx task patch

Section titled “apx task patch”
Terminal window
apx task patch <id> \
  [--title <text>] \
  [--body <text>] \
  [--due <date>] \
  [--agent <slug>] \
  [--tag <name>]... \
  [--project <name|id|path>]

--tag replaces the tag list when provided; passing no --tag flags leaves tags unchanged.

Terminal window
apx task patch t_abc123 --project myapp --title "New title"
apx task patch t_abc123 --project myapp --tag review --tag urgent   # replaces tags
apx task patch t_abc123 --project myapp --due 2026-06-10

ID format and prefix addressing

Section titled “ID format and prefix addressing”

Task IDs have the form t_ + 6 base36 characters (32-bit entropy, ~4 billion keyspace). You can address a task by any prefix of ≥ 3 characters as long as it uniquely identifies one task. If two tasks share a prefix, the command returns an error — use a longer prefix.

Terminal window
apx task done t_abc123 --project myapp     # full id
apx task done abc      --project myapp     # prefix, resolves if unique

Task fields

Section titled “Task fields”
FieldWhenNotes
titleRequiredShort imperative line.
bodyOptionalLonger notes. Markdown accepted.
tagsOptionalFree-form strings. Filterable with --tag.
dueOptionalISO date YYYY-MM-DD. Filterable with --due-before.
agentOptionalAgent slug responsible for the task.
sourceAuto / optionalOrigin: cli, telegram, super-agent, …
stateDerivedopen → done or dropped. Reopenable.

How the super-agent feeds tasks

Section titled “How the super-agent feeds tasks”

The super-agent has create_task and list_tasks tools registered in its core tool set, available on every channel. When you say “remind me to close the auth bug in myapp”, the model calls create_task with the right project, title, and optional fields. When you ask “what’s pending in myapp?”, it calls list_tasks.

Example tool call the model emits:

{
  "name": "create_task",
  "arguments": {
    "project": "myapp",
    "title": "Close auth bug",
    "due": "2026-06-01",
    "tags": ["bug"]
  }
}

If the project is ambiguous (user didn’t say which one), the model calls list_projects first and asks — it never assumes. In a Telegram channel pinned to a project, the model uses that project as the default context.

Next

Section titled “Next”
  • Routines — schedule the super-agent to create or report on tasks.
  • Super-agent — the tool loop that can create and query tasks conversationally.