Managing tasks

A Task keeps one piece of work, its responsibility, decisions, and evidence together. Use it to give someone a clear outcome, steer work already underway, and understand what happened.

Create a Task

Choose Create task, the first entry of the sidebar's navigation below Search, or press C. The dialog opens over whatever page you are on, so you can write a Task down without leaving Chats, Inbox, Library or any other page. The Tasks and Proposed pages have their own Create task button, and the command center offers the same action. A narrow sidebar shows only the plus icon, and on a phone the entry sits in the navigation menu. The entry needs permission to create Tasks. A Workspace without a Project still shows it, and the dialog first asks you to create the first Project when you may, then returns to the Task.

Write an action-oriented Title and a Description with the inputs, constraints, and result you want to review. The same property chips as on a Task page sit below them, in Create task and Edit task alike: Status, Priority, People, and Project always, and When, Repository, Time budget, Goal, and Labels behind + Add until you set them. Set an implementer or a Team, then add priority, a due date, a time budget, a Goal, and labels as needed.

The Project, Goal, Repository, and Labels chips show 25 choices at a time and search all of them as you type. When you type a name that matches nothing and you may create that kind of record, the list offers Create with your text. For a Project, Goal, or Repository it opens the usual create dialog above the Task with the name filled in, and your draft stays exactly as it was. When you save it, it becomes your choice and you continue where you were. A label is made in the Project selected for the Task. Without the permission to manage Projects, the list offers no Create. The People chip keeps its Implementer, Planner, and Reviewer lists inside its panel, without Create.

When you choose Create task, Task Machine first checks for similar work. It can then suggest details you left at their automatic defaults, such as the Project, implementer, labels or priority. Your title, description and deliberate selections stay as entered. English timing in your brief can also supply a deadline or schedule suggestion.

Useful suggestions appear in an editable review, using the same presentation as Goal coaching. Changed details have a subtle highlight and a sparkle you can hover, focus or tap to see the original choice. Returning a field to its original value removes the highlight.

The normal title and description fields stay editable throughout review, without losing the reviewed details or attachments. Choose Create task to save the reviewed choices and your edits, or Save as entered to keep the original submission. Editing does not request new suggestions. If your wording or Project changes, Task Machine checks it for duplicates before creating the Task.

If there are no useful suggestions, or the check is unavailable, the Task is created without an extra confirmation. The check uses workspace usage and follows the workspace's AI-processing restrictions. A failed ordinary validation or attachment upload keeps the form open so you can correct it.

During creation, Task Machine also checks the brief's Task Type and whether it requires source-code changes before automatic work can start. This separate check uses workspace usage and the same AI-processing restrictions. Creation continues normally when it is unavailable. A completed classification is kept without evaluating that Task again, including when no type fits. Task Types appear in Analytics, not as another field to configure on the Task.

Guided onboarding helps define your first job through a conversation and a confirmation of what will happen. An Agent's later investigation and Task spec are separate from writing that initial brief.

Keep work in Backlog until it is ready. Direct Agent work in Todo can enter planning and execution when its permissions, approvals, dependencies, budget, and execution capacity allow it. A Team lead can triage Team-owned Backlog work before routing it.

Read a Task's properties

On a Task's detail page, your description saves automatically after you pause typing. Its editor shows save status beside Undo and Redo, which reverse your own text edits even after saving. If saving fails, your text stays in the editor with a Retry action. If someone changes the description first, compare their current text before choosing which text to keep. Create task and Edit task dialogs still save their complete forms only when you submit them.

A Task's properties sit as chips in its description card, below the attachments: Status, Priority, People, and Project always, and When, Repository, Time budget, and Labels once they are set. Choose + Add to set one of the others. The column beside the description shows only what applies to the Task, such as its relationships, pull requests, and the Time and Usage cards once work has started. Plan and Review belong in Activity. Set a budget for the Task from its ⋯ menu. Members who can read a Task but cannot update it see the saved values in locked chips, without + Add, editing controls, or properties that were never set.

Choosing Cancelled or Blocked as the Status first opens a dialog where you can add an optional reason. It appears in Activity as your comment and does not start Agent work. See Blocked work.

Set a deadline

Open When and set Due by to the moment the work should be finished. When has a tab each for Due by, Scheduled for (a single run at a set time), and Repeats (recurring work), and its button summarizes whatever is set. A Task either runs once at a scheduled time or repeats, so setting one clears the other. Choose a day to make the Task due at the end of that day in your saved timezone, or select Set a time to enter an exact local time. You can change the input timezone before saving. If no valid timezone is available, Task Machine uses UTC.

Everyone shares the same deadline, displayed in their own timezone. Changing your account timezone changes the label, not when the Task is due. Tasks with no deadline sort last when you order by due date. A deadline does not schedule work to start. Use Schedules for deferred or recurring work.

Older date-only deadlines use the end of their stated UTC day because the original input timezone was not recorded. Existing deadlines with a time keep that exact moment.

Give work a time target

Use + Add, then Time budget, when the work needs to fit an effort estimate. It is available when you create or edit a Task, too. Enter Hours and Minutes as whole numbers, then choose Save, which closes the popover. Minutes above 59 roll into hours, so 90 minutes saves as 1 hour 30 minutes.

The property stays hidden until you add it. Choose Clear, or save zero hours and zero minutes, to remove the target. This is separate from the delivery deadline and the spending budget in the Task's menu.

Task Machine reserves 10% of your entry for planning, up to 30 minutes. The remainder is the work limit for the Agent's implementation, required checks, review and rework after approval. A two-hour entry gives planning 12 minutes and a work limit of 1 hour 48 minutes.

Agents see the work limit while planning. Their reminders follow the stricter of the plan's estimate and the work limit, so a tight budget adds urgency without hiding an honest estimate. When a saved budget undercuts a pending or approved plan's estimate, Task Machine records one replan prompt in the plan's discussion so the Agent re-plans within the work limit or explains why it cannot fit. Retries share the time already spent, including unsuccessful attempts, while time parked for an external decision does not count. The target never stops work or weakens required checks. See Task specs for how it appears beside the Agent's estimate.

Choose a view

Use the view that matches the work you need to check:

• All shows work across the Workspace.
• Mine shows Tasks assigned to you.
• Needs attention collects blocked work, open questions, and review states. It also shows how long each Task has been in its current state.
• Running now shows Tasks with active Agent work. Home previews the first eight.

Triage sits immediately after Tasks. Scheduled, Recurring, Proposed, and Archived follow it. Each tab appears only while it holds work you can see.

Switch between List and Board without changing the underlying Tasks. Board groups cards by status and lets you move work by dragging a card. Your layout preference follows you across Projects.

In List, each Task is one row: its priority, a status icon (hover over it for the status name), its number, and its title with any labels. Labels shorten before the title does. To see a Task's Project, who is implementing it, or when it is due, use Filter and View options instead of reading a column.

In Board, open View options to choose which status columns appear and to group them. Backlog, Todo, In progress, In review, and Blocked are shown at first. Done and Cancelled stay hidden until you select them. Hidden columns are not loaded on the Board, including during search or filtering. Your column choices follow your account across Workspaces, while List keeps its own independent view.

Cards keep Project and Goal context visible. Their shared status icon shows Task-wide questions, while dependency and requirements-check outcomes keep an independent indicator. Blocks relationships and pull-request readiness stay visible as context.

Recognize an unanswered question

A blue question mark means a question about the Task as a whole is awaiting an answer. Hover over or focus the status icon to read Awaiting an answer. List, Board, the Task header, and previews share this mark without changing the saved Status or Board column. Answer the question in Inbox or its Task conversation.

Archived work, delivery risk, and finished or blocked states retain their icons ahead of a question. A question takes precedence over Team routing. Questions inside separate conversations do not change the Task-wide icon, and Run activity keeps its own corner dot.

Recognize Team routing

A blue routing icon marks work still in Team routing, including a recommendation waiting for review or work deferred until a later time. Hover over the icon to read Team routing and, when deferred, its reconsideration time in your saved timezone. The icon appears when you can read both the Task and its Team.

Routing changes the icon, not the Task's saved Status or Board column. Archived work, delivery risk, finished or blocked states, and the blue question mark take precedence.

See what is running

The live dot on a Task row or card shows its execution state:

• Blue: Up next. Selected for the next compatible execution slot.
• Yellow: Queued. Waiting for execution.
• Green: Running. Agent work is underway.

Hover, focus, or tap the status icon to read the state. The Task header shows the same icon in front of the title, with the same tooltip.

Search, filter, and arrange

Search by a Task identifier, words from its brief, or a related concept. On Scheduled and Recurring, search also finds Workflows by name or description.

The Filter button sits beside the search. On Tasks it narrows the work by status, priority, implementer, Team, Involves, Project, Goal, label, creator, origin, or current activity. Choose a filter type, then the values you want. Any human, Any agent, and Any team at the top of Implementer keep work owned by that kind of implementer. Workflow-created Tasks have a Workflow origin. Starting a Workflow against an existing Task does not change that Task's original source.

Involves finds the work a person, an agent, or a Team has a hand in, whatever their role. Choose an agent or person and you see the Tasks they implement, plan, or review, plus the Tasks where they wrote a comment, for example an agent you tagged in a thread for input and who replied. Deleted comments and comments imported from Intake or feedback do not count. Choose a Team and you see the Tasks it implements or routed. Involves lists only the agents, people, and Teams you can see, and it combines with the other filters like any filter, so it also works in a pinned view.

Archived, Scheduled, and Recurring filter by implementer and Project, and Proposed by who proposed the Task and its Project. A Scheduled or Recurring list filtered this way shows Tasks only, because Workflow schedules have no implementer or Project.

Each active filter appears as a chip under the tabs. Remove a chip with its ×, or clear them all with the eraser button. The pin button beside Filter saves the filtered view, on any of these tabs, as your own tab between Recurring and Proposed and in your sidebar. Choose the pin button again on a pinned view to remove it.

View options, the eye button beside Filter, chooses grouping, order, and sort direction. In Board, grouping splits each status column into labeled swimlanes, a Task with several labels appears in each of its label lanes, and unlabeled work collects in a No label lane. The same menu also controls which columns appear. Filters narrow the columns you chose to show and do not reveal hidden columns. Phones always show the List, so their View options sort and group it.

Separate routing from work underway

Open Triage to see Team-owned Backlog work separately from the Tasks already underway. The page brings together your pending routing decisions and work Waiting on the lead, including deferred Tasks with their reconsideration times. Routing metrics at the top cover the last seven days. Correction rate and typical triage time appear once completed reviews support them.

Use Filter beside the tabs to combine Projects, Goals and members. The filter offers only what has someone triaging. A Project or Team appears once it has a lead, a Goal appears when such a Project or Team sits below it, and Member is one list of Teams first, then Agents, then the people who lead a Team or a Project. Choosing a Team shows the work it owns, including work a Project lead routed to it. Choosing a person shows the work they triage and work handed straight to them.

The same selection narrows both previews and the routing metrics. Selected filters stay in the page URL. If a selected Team or Project later loses its lead, the selection stays applied and its chip adds (no lead), so you can still see its work and remove it. The navigation badge remains the total of your pending routing decisions.

Choose a Needs you row to open its review in the global Inbox drawer without leaving the page. Open Inbox or View more opens the full Triage list with the overview's filters applied. The Previous inbox item and Next inbox item buttons continue through that list, including later pages, without closing the modal. Its order follows your saved Inbox sort.

Each preview shows up to five items. Waiting work opens the Task for inspection or manual steering. It has no pending routing recommendation yet. The waiting preview requires Task and Team read access, while routing metrics require Team read access. Your own Inbox decisions remain available independently. See Team lead routing for the decisions and their consequences.

Steer active work

Change the brief when the intended result changes. Use a comment for a specific correction or question, and change the implementer when responsibility should move. These changes stay in the Task's history.

Follow the next step

Every Agent run ends with a report of where the work stands and what should happen next, such as continuing implementation, checking CI again at a chosen time, or waiting for a decision. With an installed Events Connector, the Agent can wait for a matching service event instead of checking repeatedly. It always chooses a check time as well, so the Task can continue if no event arrives.

The matching event or check time makes the same next step ready. No Worker stays running just to wait, and approval, dependency, budget and execution checks still apply. An event never approves an action on your behalf. Task Machine starts the step when those checks permit it, without you starting each run.

The tooltip of the status icon in the Task detail header shows the next step and what it waits for. The Runs tab opens with a Next step card that shows the step, its instruction, and the reason the Agent gave, above the steps taken so far, described below. Task cards and list rows show the same step in the same tooltip, and the icon's corner badge also shows when a Run is queued, running, or needs recovery.

An Event wait shows Waiting for updates. Hover over the badge, focus it with the keyboard, or tap it to see when Task Machine will recheck if no event arrives.

Event received means a matching event arrived, not that a Run has started or that its approvals are complete. Waiting to retry means an update arrived but the next attempt must wait until the time shown in its tooltip.

If the connection stops receiving events, the saved check time remains. See Blocked work for rechecks and Run next.

When runs keep failing, ending without a report, or failing to start, the step stops and shows Needs recovery with the cause. A Task needs recovery item keeps that cause, the affected runs, and both resolution actions in Inbox. Successful execution keeps its actual outcome even when the task needs recovery.

Choose Give direction to tell the assigned agent how to proceed through a comment, or Run again to request the current step. Both follow the normal execution checks and preserve earlier evidence without replaying an old run. The same controls remain available on the Task. When the runs themselves failed, the card at the top of the task and the Next step card also offer Report to Task Machine, which opens the feedback form with the failure described for you to review and send. See Setup and recovery for the Inbox flow and Blocked work for waiting and recovery.

Monitor a changing condition

For a condition that changes outside Task Machine, the Agent can choose a bounded monitoring loop instead of scheduling each check separately. For example, it can check for a new Node security release hourly, then hand the available update back to the Agent responsible for the work.

The Agent chooses an interval from 15 minutes through 24 hours and up to 100 checks. The interval multiplied by the check count must fit within 30 days. The first accepted schedule also expires after 30 days, even if execution has been unavailable. A request outside these limits is rejected rather than silently changed.

The Next step card shows what is being monitored, the interval, checks used and allowed, the next check time, and when the allowance expires. Each started checking Run uses one check, including a failed check or a retry in a new Run. No Worker stays running between checks, checks never overlap, and missed checks do not accumulate. Approvals, dependencies and budgets still apply.

An unchanged result keeps the same allowance. Finding the condition ends monitoring and returns to the ordinary next-step rules, without approving an action or completing the Task. When the checks or time run out, monitoring stops and Inbox offers Renew monitoring or Stop monitoring, with the schedule and last observation beside the decision. Renewal permits another bounded set of checks at the same interval. Stop leaves the Task unfinished and schedules no more checks. The same controls are available on the Task to members who can update it.

Only an explicit renewal replenishes the allowance. Run next, Retry, report corrections and reworded instructions cannot reset it or bring a check forward before its interval.

See where a Task stands

Agents choose their own path through a Task, so its status alone cannot show how far the work has come. The card at the top of the Runs tab shows what Task Machine knows: the next step, the steps already taken, and the stages still ahead. It never guesses a step that has not happened.

The card is titled Next step, and a small pulsing dot beside the title shows while a run is working on the step. A Task without a next step, such as a finished one, titles the card Steps.

Below the next step, the list reads from the start. Each step shows what it was, the Agent that did it, and when. A step that did not succeed says so, and repeated checks, such as CI, collapse into one row with a count. The list shows the latest steps, and every run stays in the list below the card. Long lists start collapsed. Choose Show all steps to reveal the rest, or Show fewer steps to collapse them again.

The stages still ahead stay grey at the end of the list. They are Planning, Implementation, Code review, Review, and Done.

A stage appears once the Task has used it or is expected to use it. Planning shows when the Task has a plan, Code review when an Agent works on code in a repository, and Review when someone is assigned to review the result. When review feedback sends the work back to the Agent, the stages after Implementation turn grey again.

A finished Task ends with Done, and a cancelled Task ends with the stage where it stopped. Anyone who can read the Task can see the card, and it updates as runs finish and the next step changes.

A Task that runs a Workflow

A Workflow already defines its own path, so a Task that runs one shows that path in the same card instead of the stages above. The card is titled by the Workflow, with a pulsing dot while it runs and the state of the run at the right, the way Next step shows its state. If the Task also has a next step, Next step leads as usual and the Workflow follows below it.

Choose Run details to open the run and read each step's output and the items a loop worked through. Below it, every step reads like any other step in the card: a check mark when it succeeded, a badge when it is running, waiting for a person, failed or skipped, and a grey mark while it has not started. A line under each title says what kind of step it is, and what it used when that is known. Parallel branches appear as indented paths, and a loop appears as one step. The step the run is at has a badge, and the card updates as the run goes on.

The newest run is the card, so the list of runs below shows only the earlier ones.

Keep delivery on schedule

The root of a schedule defines future work and has no delivery target or delivery-risk warning, even if it keeps an older due date. Each execution Task has its own target.

A Task carrying out work uses its due date as the delivery target when one is set. Otherwise it is the time work started plus a window for its priority: 8 hours for Urgent, 3 days for High, 7 days for Medium, 10 days for Low, and 14 days without a priority. Agents report their estimated remaining working time at the end of every run. The Time card shows the time left until the target and the latest estimate, and the status icon becomes a orange warning triangle when the estimate no longer fits. Hover, focus, or tap it to read why. A finished or cancelled Task keeps its Done or Cancelled icon, and its tooltip says how late it ended when it missed the target.

For an agent task, the default target moves later while work waits for a person's decision, another task, a Task Machine fix, budget, or an available worker. Overlapping waits count once. Time spent running, waiting for capacity, checking CI, or waiting until a time the agent chose does not extend the target. A due date you set never moves automatically.

The agent's time guidance uses the plan's total working estimate, or the work limit of a time budget when that is smaller, with 80% for implementation, 5% for review and 15% for rework. Actual work across attempts consumes each allowance, including unsuccessful attempts and work before a pause. Waiting never reduces it, and Planning, Discussion and Recheck have no time budget.

A reminder arrives when a bucket reaches 75% of its allowance and another at 100%. The agent also gets a time check for every 15 minutes of work on the Task, including after the allowance is used up, naming the time worked and the time left or over. Going over means focus on the essential work and continue in the same run. Required checks and review stay in place. Changing priority or a deadline changes delivery context, not the effort allowances. Changing Time budget updates them when its work limit is the smaller basis. The Time card shows the total estimate beside the delivery target and latest remaining estimate. See Duration and usage.

A Run without a new estimate keeps the previous one. Decisions waiting in Inbox become at least High when the Task is Urgent, its delivery target is within 24 hours or has passed, or its latest estimate no longer fits. The urgency marker explains the reason, and Priority ordering allows time for the remaining work before the target.

Urgent and High work starts ahead of other Agent work, Urgent first. Run next starts the Task's current next step now, even when the Agent planned it for later, except that a monitoring loop retains its interval and allowance. Project fairness shares the remaining capacity.

Run next does not interrupt work already running, change the Task's Priority or due date, or bypass approval, dependency, budget, and execution checks. See Assignments and dependencies for routing and queue behavior.

Move a Task to another Project

Choose another active Project from the Task detail page. Review the confirmation before moving it:

• The Task receives the next identifier in the destination Project.
• Labels from the previous Project are removed.
• A Goal unavailable in the destination Project is cleared.
• An explicitly selected repository stays attached. Otherwise, the destination Project's default applies.

Queued or running Agent work must finish or be cancelled first. Previous Task identifiers remain reserved and redirect to the current identifier, so an old link cannot open different work.

Archive and restore finished work

A Done or Cancelled Task is archived after seven days without an update, during the next hourly cleanup. Other statuses are not automatically archived.

Open Archived after Proposed in the primary Tasks tabs to find past work without adding it back to your active views. The tab appears only when you can access Tasks and have archived work to read. Archived is a separate, searchable list that loads more history as you scroll, not a Board or another active-work filter view. Open a Task to read its history, or choose Restore task from its ⋯ menu when you have permission to change it.

Archiving keeps the terminal status and history. Lists, Board cards, and the detail header show an archive icon in place of the status icon, and its tooltip says Archived, until you restore the Task. Archived Tasks cannot be edited. Restore one before changing its properties, brief or assignment.

In tama, Task reads default to active work. Add --status archived to find or inspect archived Tasks, or --status all to include both. History remains available by UUID, current identifier, or a retained identifier from a previous Project. Reading history does not restore the Task or start Agent work, and archived Tasks cannot be edited through these commands.

tama tasks show returns bounded history pages. Use each collection's page_info and next_cursor with --collection and --after to read older records. See the CLI command reference for examples.

Attach files

Drop files anywhere on a Task's description, or choose + Add and then Attachment. Attachments, images included, are listed under the description, where you can preview, download, or remove them. Each file can be up to 250 MB.

Task Activity

Open Activity for comments, status changes, questions, approvals, and the Task's Plan and Review discussions. Once an Agent reports on the work, a Summary tab next to it holds the current outcome, and finished Tasks open on it. On a completed Task, Make this repeatable in Summary starts a Chat about turning the work into a Workflow. Related generated updates collapse into a task update row that you can expand for the individual details, authors, and times.

The Plan block brings the proposed approach and planning discussion together. The Review block brings recorded checks, the submitted result and review discussion together. Decided work leaves a small card at the time of its outcome. See Task specs and Reviews.

Each comment thread opens on its latest five comments in chronological order. Select Load earlier replies to read older context in the same thread. When you can read Agents, an Agent author's name links to that Agent's profile.

Activity shows queued and running work while it is active. A failure stays visible until newer work starts. Successful, cancelled, and superseded Runs stay in Run history rather than crowding the conversation.

Activity shows a decision card while you can act on the Task, such as approving evidence, allowing a tool call or restoring blocked work. After you approve or reject a Task approval request in a conversation, its card keeps the original request, outcome, deciding person and time. Open it for the saved decision details, without approval controls. Other decided, withdrawn, stale and cleared cards leave Activity. Their conversations and evidence remain, and you can find past decisions in Inbox. Memory, Skill, Agent and Project proposals stay in Inbox, even when an Agent proposed them while working on this Task.

When you have permission to grant credential access, you can approve or reject a Task's waiting access request from Activity using the same controls as Inbox. Permission to edit the Task alone does not let you grant access.

Questions stay with their comment threads. Approval cards appear in the conversation that prompted them when that context is attached, or at the top level when they stand alone. A new approval from an Agent conversation can still appear in its thread after the Task is Done, until the Task is archived. Responding does not reopen the Task. You can still resolve the corresponding request in Inbox without reconstructing the history here.

Comments and mentions

Use a comment to correct the work, ask a question, or bring in a person, Agent, or Team. Attach the evidence they need rather than making them search for it. Comments and attachments explains replies, mentions, reactions, and Agent handoffs.

Labels

Use Project-owned labels to classify work consistently. Labels explains how to create, propose, apply, archive, and restore them.

Blocked work

A dependency and a Blocked status are different. Assignments and dependencies covers work waiting on another Task. Blocked work covers recorded reasons, rechecks, and requests for your help.

Review results and execution

Use Task specs for the proposed approach and Task reviews for review decisions. Run history, Browser use, and Duration and usage explain the execution evidence.

Schedules covers deferred and recurring work. Coding Work explains repository access and pull-request delivery.