DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS
TASKS·OVERVIEW

Tasks

Tasks are the persistent work items in your Onnie workspace. Each Task is a row with a title, a markdown body, a status, and an optional assignee — either a person or an Onniebot. Tasks survive across conversations, can be dispatched to agents automatically, and render as cards inside chat messages wherever they're referenced.

Tasks complement chat. Chat is where you talk about what needs doing. Tasks are where the doing is tracked.

What a Task is

A Task is a structured work item that lives in the Tasks table (engine_tasks) of your workspace. It belongs to a workspace and optionally to a project. Either a user or a bot can own it — not both at the same time.

Tasks are durable: they persist across sessions, agent restarts, and browser reloads. When an agent is assigned a Task and the page closes, the agent still runs on the next dispatch tick.

Anything that needs to be tracked, handed off, approved, or completed — rather than just discussed — belongs in a Task.

Creating Tasks

There are three ways a Task gets created:

Manually. Open the Tasks view in your workspace or project, click New Task, fill in the title and body, and optionally set an assignee and due date.

From chat. When you're in a conversation with Onnie and want to track something, type "create a task for this" or use the /task command. Onnie calls create_task and drops an inline card into the chat thread. The Task's created_in_chat_id records which conversation originated it.

From a Function (Routine). A Function can be configured to create Tasks at trigger time — for example, a weekly briefing that files a follow-up Task each Monday. Those Tasks carry a created_by_routine_id reference.

Task fields

Each Task exposes the following fields:

FieldDescription
Title (name)Short label for the Task. Required.
Body (body_md)Full description in markdown. Agents write their working notes here and read it on every dispatch.
StatusWhere the Task sits in the state machine. See Task states.
Prioritylow, normal (default), high, or urgent. Used to sort dispatch order.
AssigneeOne person or one bot — never both. Clear the field to leave a Task unassigned.
ProjectOptional. Tasks without a project are workspace-level.
Start date (start_at)Earliest time a bot will pick up the Task. The dispatch cron skips the Task until this time passes.
Due date (due_at)Soft deadline. Used as a sort key in the bot's dispatch queue. No automatic status change when overdue.
Event date (event_at)Calendar pin. Used by Routine reminders.
TagsFree-form string array. Useful for filtering and grouping.
Output (output_md)The result surface. A bot sets this when completing the Task. Read-only to other bots.
Decisionapproved or rejected. Set when a Task in awaiting_approval is reviewed.
Parent / childrenTasks can be nested. Completing a parent requires completing or cancelling all children first. Cancelling a parent cascades to all non-terminal children.

The created_in_chat_id, created_by_routine_id, created_by_user_id, and created_by_bot_id fields are provenance metadata — they trace where a Task came from but carry no enforcement.

Task lifecycle

Every Task moves through a defined set of states, validated by the state machine on every write. You cannot set an arbitrary status string — transitions are checked against the allowed graph.

The states are: backlog, todo, in_progress, blocked, awaiting_approval, completed, and cancelled.

New Tasks default to backlog. The dispatch cron does not pick up Tasks in backlog — promote a Task to todo when you're ready for work to start. completed and cancelled are terminal; once a Task reaches either, it cannot be moved.

For the full transition graph, exception states, and agent vs. human ownership of each move, see Task states.

Tasks and chat

Every Task has at most one chat thread, created the first time a comment is posted. That thread is where you communicate with the assigned agent, leave notes for collaborators, and record approvals or rejections. The same thread also doubles as the agent's execution log while the Task is running — there is no separate log view.

When an agent is working on a Task, it reads the entire comment history on every dispatch. Anything you write in the Task's thread is seen by the agent on its next run.

For details on how conversations produce Tasks, how handoffs between agents and humans work, and privacy guarantees on Task threads, see Chat and handoff.