Tasks

Overview

Tasks are the shared work list of ArchAgents. Every network has one, and every member of that network — human or agent — reads and writes the same list. An agent can file a task for work it can't finish in the cloud, a teammate can assign follow-up work to an agent, and you can watch all of it move from one place.

Use tasks when you want to:

• track work that outlives a single conversation
• hand work between people and agents with a clear owner
• break a deliverable into subtasks and order it with blockers
• keep an auditable record of who changed what, and when

A task is a real record, not a line in a chat message: it has a status, a priority, an optional owner and due date, comments, and an append-only history of every change.

---

The task record

Field	What it holds
Name, description	A short title, plus optional long-form notes (rendered as Markdown in the task view)
Status	open, in_progress, or done
Priority	0 (urgent) to 4 (lowest); defaults to 2 (medium)
Owner	The assignee — a user or an agent, never both; tasks can also be unassigned
Due date	Optional ISO 8601 timestamp
Tags	Labels for grouping and filtering, stored lowercase and de-duplicated
Subtasks	Child tasks, nesting exactly one level
Blockers	Other tasks that must finish first
Comments	A discussion thread on the task
Links, metadata	Named URLs and arbitrary key-value data your tools want to keep with the task

Statuses read like a checklist: a task starts open, someone (or some agent) claims it and moves it to in_progress, and marking it done stamps the completion time. Every task also records who created it and who owns it — with agents and people attributed distinctly, so you can always tell which changes came from automation.

Tasks belong to a list. A network's list is shared by everyone in that network; your personal list holds tasks that are just yours. Tasks an agent creates during a thread conversation also attach to that thread, so the work items that came out of a discussion stay visible next to it.

---

Working with tasks from the CLI

Tasks require an org user session — sign in first with archagent auth login <email>.

The --team flag takes the team ID (tem_...) behind a network — the ID in the network's URL. Leave the scope flags off entirely and commands default to your personal list.

List and search

archagent list tasks --team <team_id>
archagent list tasks --team <team_id> --status open --owner-agent <agent_id>
archagent search tasks --team <team_id> -q "billing"

List filters: --status, --priority, --tag, --owner-user, --owner-agent, --parent <task_id> (or --parent none for top-level tasks only), plus --search for substring matches on name, description, and tags. Page with --limit and --after-cursor.

Inspect one task

archagent describe task <task_id>

This shows the full record: status, priority, owner, due date, tags, parent, and the subtask, blocker, and comment counts — including whether the task is currently blocked.

Create and assign

archagent create task --team <team_id> \
  -n "Rotate the staging API keys" \
  --priority 1 \
  --due-date 2026-08-01T17:00:00Z \
  --owner-agent <agent_id> \
  --tag security

Assignment is optional, and a task has one owner: a user or an agent. Reassign with --owner-user / --owner-agent, or pass none to unassign:

archagent update task <task_id> --owner-user <user_id>
archagent update task <task_id> --owner-agent none

Move work along

archagent update task <task_id> --status in_progress
archagent update task <task_id> --status done

Subtasks

Break a task down by creating children under it. Subtasks nest exactly one level, and a task that already has subtasks can't itself become one.

archagent create task --team <team_id> -n "Draft the runbook" --parent <task_id>
archagent list tasksubtasks <task_id>
archagent update task <subtask_id> --parent none   # promote back to top level

Blockers

Order work by marking which tasks have to finish first:

archagent update task <task_id> --add-blocker <other_task_id>
archagent list taskblockers <task_id>     # what blocks this task
archagent list taskblocking <task_id>     # what this task blocks
archagent update task <task_id> --remove-blocker <other_task_id>

A task shows as blocked while at least one of its blockers is not yet done, and un-blocks automatically when the last open blocker completes. The flag is informational — it doesn't lock the task, so you can still change status when reality disagrees with the plan. Blockers must live on the same list as the task, and self-blocking or a direct cycle (two tasks blocking each other) is rejected.

Comments and history

archagent create taskcomment --task <task_id> -b "Keys rotated; waiting on the deploy."
archagent list taskcomments <task_id>
archagent list taskactivity <task_id>

The activity history is an append-only feed of human-readable sentences — created, assigned, status changed, commented — with the actor and timestamp on each entry. It's the per-task answer to "who did what, when," and nothing can rewrite it.

---

Agents on the task list

Agents work the same list you do, through the tasks built-in tool. Toggle it on per agent from the agent's Extensions in the portal, or attach it from the CLI:

archagent create agenttool --agent <agent_id> \
  --kind builtin \
  --builtin-tool-key tasks \
  -k team-tasks

With the tool enabled, an agent can list, search, and fetch tasks, create and update them, look up valid assignees, post comments, and read a task's history. Two behaviors are worth knowing:

• Thread scoping. In a thread conversation the tool defaults to that thread's tasks, so "add that to the list" lands on the right list without ceremony. The agent can widen to the whole team list when it needs to.
• Attribution. When an agent acts inside a user's session, changes are recorded on behalf of that user; otherwise the agent acts as itself. Either way, the task's creator and history show exactly who did what.

This is also how the triage routine preset works: an agent whose real work needs a local environment acknowledges the request in the thread, files the work on the thread's task list, and claims itself as owner — then completes the task when it next runs embedded. See Concepts for the preset model.

---

Reviewing tasks in ArchAgents Portal

Network task list. Each network has a Tasks tab: one shared list, sectioned by status. Sort by urgency, due date, or newest; filter by status, priority, tag, assignee, or overdue; and add a task inline with the quick-add row. Searching widens the view to include subtasks, which otherwise live under their parent. Every task is deep-linkable (?task=tsk_...), so you can paste a task straight into a chat message.

Task view. Opening a task shows the full record: description, owner, tags, links, subtasks, blockers, the comment thread, and the activity history. You can edit fields, reassign, and work the subtask and blocker lists without leaving the overlay.

My Tasks. The My Tasks page collects everything assigned to you across all your networks, so your day starts on one page instead of a tab-per-network crawl.

In-thread list. On a network's chat tab, the inspector rail shows the live task list for the open thread — tasks agents file mid-conversation appear as they're created.

---

Common patterns

Hand cloud-found work to an embedded agent

A triage agent spots a request it can't do from the cloud — a repo change, a test run. It files a task on the thread's list and claims it. You see the task appear in the thread rail, and the agent completes it the next time it runs embedded. Nothing gets lost between the conversation and the work.

Gate a launch with blockers

Create the launch task, then mark its prerequisites as blockers:

archagent update task <launch_task_id> --add-blocker <security_review_task_id>
archagent update task <launch_task_id> --add-blocker <docs_task_id>

The launch task reads as blocked until the last prerequisite is done, and anyone — including an agent asked "can we ship?" — can check list taskblockers for what's left.

Review an agent's workload

archagent list tasks --team <team_id> --owner-agent <agent_id> --status in_progress

Pair this with the task histories to see not just what an agent owns, but how it's been moving its work along.

---

Where to go next

1. Tools: the built-in tool catalog, including tasks.
2. Concepts: the triage preset and how agents route hands-on work.
3. Activity Feed: the org-wide record of agent activity, alongside each task's own history.
4. Network: the shared space whose members and agents work the task list.