A task is a coding assignment you give to an AI agent. You describe what needs to be done — in plain language or as a detailed spec — and Optio provisions an isolated environment, runs the agent, opens a pull request, and drives the PR to completion through CI, review, and merge. Every task belongs to a repository and is processed by the agent you select (Claude Code or OpenAI Codex). You can monitor live agent output, track PR status, and manage the queue from the Tasks page.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/jonwiggins/optio/llms.txt
Use this file to discover all available pages before exploring further.
Creating a task
Open the new task form
Navigate to Tasks in the sidebar and click New Task, or go directly to
/tasks/new.Fill in the title and description
Give the task a concise title (e.g., “Add pagination to the users API”). In the description field, write the full prompt the agent will receive. Be specific: include acceptance criteria, file paths, coding conventions, or any context the agent needs.
Select a repository
Choose the repository this task should run against. The agent will check out the repo’s default branch (or a branch you specify) and work within an isolated git worktree.
Choose an agent type
Select Claude Code or OpenAI Codex. The agent type, along with the repository’s model configuration, determines which model runs your task.
Set optional parameters
Optionally configure a branch override, priority, max retries, or task dependencies before submitting.
Task states
Every task moves through a well-defined lifecycle. The current state is shown as a colored badge on the task card and detail view.Queued
Queued
The task has been submitted and is waiting in the priority queue. Optio will pick it up as soon as a global concurrency slot and a per-repository slot are both available. If the task has unmet dependencies, it will show Waiting on dependencies instead and transition to queued automatically when those dependencies complete.
Provisioning
Provisioning
Optio is finding or creating the repository pod and preparing a git worktree for this task. This typically takes a few seconds if a warm pod already exists for the repository, or up to a minute for a cold start.
Running
Running
The agent is actively writing code in the isolated worktree. Live logs are streaming to the task detail page in real time. The agent will stop after opening a pull request.
PR Opened
PR Opened
The agent has opened a pull request. Optio’s PR watcher is now polling every 30 seconds for CI status, review state, and merge readiness. The task stays in this state until the PR is merged, closed, or requires the agent’s attention.
Needs Attention
Needs Attention
Something has interrupted the normal flow and the agent needs to resume. Common triggers include: CI checks failed, the PR has a merge conflict, or a reviewer has requested changes. Optio will automatically re-queue the agent with the relevant context if auto-resume is enabled for the repository.
Completed
Completed
The pull request was merged. If the task was linked to a GitHub Issue or Linear ticket, the ticket is closed automatically.
Failed
Failed
The task encountered an unrecoverable error — the agent crashed, the PR was closed without merging, or all retries were exhausted. The task detail page shows a classified error message with a suggested remedy. You can retry the task manually.
Cancelled
Cancelled
The task was cancelled by you or a bulk operation. A cancelled task can be re-queued by clicking Retry.
Task priority
Tasks in the queue are processed in priority order. Lower priority numbers run first. When you create a task, the default priority is100.
To reorder tasks, open the Tasks page and drag tasks into the order you want. Optio reassigns priority values based on position — the topmost task gets the lowest (highest-priority) number.
Subtasks
A task can spawn child tasks that run as part of the same pipeline. Subtasks appear nested under the parent in the task detail view.| Subtask type | Description |
|---|---|
| Child | An independent subtask that runs alongside or after the parent. |
| Step | A sequential step in a multi-stage pipeline. Steps run in order, and the parent waits for all blocking steps to complete. |
| Review | A code review subtask launched after the coding agent opens a PR. The review agent runs a separate pass and can request changes. |
Bulk operations
The Tasks page supports two bulk operations available from the Actions menu:- Retry all failed — re-queues every task currently in the
failedstate. Useful after fixing an infrastructure issue that caused widespread failures. - Cancel all active — cancels all tasks currently in
runningorqueuedstate. Use this to clear the queue before a deployment or maintenance window.
Task dependencies
A task can be set to wait for one or more other tasks to complete before it starts. This lets you chain work sequentially — for example, run a database migration task before a task that uses the new schema. When creating a task, expand Advanced options and select the tasks this task depends on. A task with unmet dependencies stays in thewaiting_on_deps state and is automatically queued once all upstream tasks complete successfully.
If a dependency task fails, the downstream task also transitions to
failed to prevent running code that depends on incomplete work.