Tasks

APX tiene una lista de TODO por proyecto respaldada por un log de eventos solo-agregado. Las tasks tienen alcance de proyecto, se direccionan por prefijo de short-id, y nunca se borran de verdad — las transiciones de estado (done, drop) se registran como eventos y la task persiste para siempre.

Almacenamiento

Las tasks viven en ~/.apx/projects/<apxId>/tasks/YYYY-MM.jsonl, un archivo por mes. El estado es el fold del stream de eventos: crear, completar, descartar, reabrir y parchear, todos agregan eventos. No hagas grep del JSONL directamente para conocer el estado — usá apx task list o la API.

apx task add

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

--tag es repetible. Ejemplos:

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

Precaución

Pasá siempre --project. Sin eso, la task cae en el primer proyecto registrado (o el id=0 por defecto), que probablemente no es lo que querías.

apx task list

apx task list \
  [--state open|done|dropped|all] \   # por defecto: open
  [--status pending|running|in_review|blocked] \
  [--tag <nombre>] \
  [--agent <slug>] \
  [--due-before <iso>] \
  [--due-after <iso>] \
  [--updated-since <iso>] \
  [--limit <N>] \
  [--all | --project <nombre|id|ruta>]

apx task list --project myapp                          # tasks abiertas
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 task list --project myapp --status blocked         # trabadas, en este proyecto

En todos los proyectos

--all junta todos los proyectos registrados en una sola lista, más reciente primero, y cada fila queda etiquetada con el proyecto del que salió. El resto de los filtros sigue aplicando.

apx task list --all                                    # todo lo abierto, en todos lados
apx task list --all --status blocked                   # qué está trabado, en todos lados
apx task list --all --updated-since 2026-08-01T00:00:00Z   # qué se movió
apx task list --all --due-before 2026-09-01 --limit 20

--state es el ciclo de vida en el almacenamiento (open / done / dropped). --status es cómo avanza una tarea abierta (pending / running / in_review / blocked). Son preguntas distintas: “qué está trabado ahora” no es “qué está abierto”.

Si el log de tareas de un proyecto no se puede leer, ese proyecto se saltea y un aviso lo nombra — un archivo ilegible nunca deja la vista entera en blanco.

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 — tasks abiertas con id, título, tags, fecha de vencimiento y agente

apx task show

apx task show <id> [--project <name|id|path>]
apx task show abc  [--project <name|id|path>]   # coincidencia por prefijo (≥ 3 chars, debe ser único)

Imprime la task completa como JSON, incluyendo todos los campos y el estado actual.

Transiciones de estado

apx task done   <id> [--project P] [--by <name>]   # marcar como completada
apx task drop   <id> [--project P]                  # archivar (ya no hace falta)
apx task reopen <id> [--project P]                  # volver a open

done significa “completé este trabajo”. drop significa “esto ya no hace falta”. Las métricas y los reportes los distinguen — usá el correcto.

apx task patch

apx task patch <id> \
  [--title <text>] \
  [--body <text>] \
  [--due <date>] \
  [--agent <slug>] \
  [--tag <name>]... \
  [--project <name|id|path>]

--tag reemplaza la lista de tags cuando se provee; no pasar ningún flag --tag deja los tags sin cambios.

apx task patch t_abc123 --project myapp --title "New title"
apx task patch t_abc123 --project myapp --tag review --tag urgent   # reemplaza los tags
apx task patch t_abc123 --project myapp --due 2026-06-10

Formato de ID y direccionamiento por prefijo

Los IDs de task tienen la forma t_ + 6 caracteres base36 (entropía de 32 bits, ~4 mil millones de keyspace). Podés direccionar una task por cualquier prefijo de ≥ 3 caracteres mientras identifique de forma única a una sola task. Si dos tasks comparten un prefijo, el comando devuelve un error — usá un prefijo más largo.

apx task done t_abc123 --project myapp     # id completo
apx task done abc      --project myapp     # prefijo, resuelve si es único

Campos de una task

Campo	Cuándo	Notas
title	Requerido	Línea imperativa corta.
body	Opcional	Notas más largas. Se acepta Markdown.
tags	Opcional	Cadenas libres. Filtrables con --tag.
due	Opcional	Fecha ISO YYYY-MM-DD. Filtrable con --due-before.
agent	Opcional	Slug del agente responsable de la task.
source	Auto / opcional	Origen: cli, telegram, super-agent, …
category	Opcional	Qué CLASE de tarea: general (por defecto) o trip. Conjunto cerrado — ver abajo.
location	Opcional	Dónde está el mandado trip: place, address, latitude/longitude, radius_m.
state	Derivado	open → done o dropped. Reabrible.

Categorías y lugares

Un tag es una etiqueta libre que inventás vos. Una categoría es un conjunto cerrado sobre el que actúa el sistema, y esa es la diferencia que importa: trip significa “un mandado, en un lugar”, y el daemon puede rutear sobre eso sin pedirle a un modelo que lea el título y adivine.

Esa adivinanza es justamente lo que reemplaza la categoría. Mientras hay un viaje en curso, APX cruza tu posición con las tareas abiertas y te avisa una vez cuando pasás cerca de algo útil. Para una tarea sin ubicación tiene que buscar lugares en OpenStreetMap que puedan servir; para una tarea trip que ya trae sus coordenadas no hace nada de eso: ni geocoding, ni búsqueda de lugares, ni llamada a un modelo. El mismo recordatorio, sin red y sin tokens.

apx task add "Comprar ibuprofeno" --category trip --place "Farmacia del Km 8" --at "-41.13,-71.31"

Sin coordenadas el mandado igual funciona, pero pasa a ser una elección: el daemon busca lugares que lo resuelvan y se queda con todos, apuntando al más cercano mientras manejás. “Comprar pan lactal en el súper” matchea panaderías y supermercados a la vez, así que vigila varios negocios hasta que uno quede fijado — porque hay uno solo, o porque contestaste “voy”. Ver Android · el plan del viaje.

--radius <m> define qué tan cerca cuenta como “ahí” para ese mandado; sin él rige el radio de movilidad por defecto. Un --place vacío en apx task patch borra la ubicación. Los tags no se tocan con nada de esto: una tarea puede tener los dos.

La lista de tareas de la web dibuja una marquita para la categoría que tiene una; general no dibuja nada, porque un ícono en todas las filas no informa.

Cómo el super-agent alimenta las tasks

Todo el ciclo de vida son herramientas, registradas en el conjunto core del super-agent y disponibles en todos los canales: create_task, list_tasks, get_task, update_task, complete_task y comment_task. Cuando decís “recordame cerrar el bug de auth en myapp”, el modelo llama a create_task con el proyecto correcto, el título y los campos opcionales. Cuando preguntás “qué está pendiente en myapp?”, llama a list_tasks.

Las filas de list_tasks son compactas a propósito — sin descripción y sin comentarios — así que todo lo que va más allá del título es get_task, que devuelve el registro completo con su hilo y sus subtareas. Editar es update_task: pasás sólo los campos que cambian, y "" para vaciar uno. Las columnas del tablero y el cierre siguen en complete_task (action: "status" | "done" | "drop" | "reopen"), que valida la columna contra el catálogo que tiene esta instalación.

Nada de una task necesita shell. Una task editada escribiendo el log JSONL se saltea todos los normalizadores del store y deja un estado que el fold no puede reconstruir.

Ejemplo de la llamada a herramienta que emite el modelo:

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

Si el proyecto es ambiguo (el usuario no dijo cuál), el modelo llama primero a list_projects y pregunta — nunca asume. En un canal de Telegram fijado a un proyecto, el modelo usa ese proyecto como contexto por defecto.

Nota

Las tasks no son un scheduler — no disparan notificaciones al vencer. Son una lista. Hay un futuro tipo de routine (task-due-notify) planeado pero todavía no construido.

Pasarle una tarea a otro agente

El trabajo para otro agente va a una tarea, no a un mensaje: asignala (create_task con ese agente) o comentá en la tarea existente mencionándolo — @qa listo para QA. Una mención en un comentario convoca al agente: toma la tarea en su propio turno y contesta en el mismo hilo. A todos los agentes se les indica que así se mueve el trabajo; hablarle directo a otro agente es para cuando estás en una conversación en vivo y necesitás esa respuesta ya.

Un hilo puede correr sin nadie mirando, así que tiene límites: un comentario arranca como mucho cuatro respuestas (cascada incluida), una tarea que ya tiene agentes trabajando en su hilo no arranca una segunda, y los agentes que se pasan una tarea de un lado a otro tienen como mucho ocho turnos por hora en ella. Tus propios comentarios no tienen tope.

Siguiente

• Routines — programá el super-agent para crear o reportar tasks.
• Super-agent — el tool loop que puede crear y consultar tasks conversacionalmente.