Creating Tasks

A Task is the unit of agent work in Optio. Every Task has a Who (agent), What (prompt), When (trigger), Why (description), and an optional Where (repo + branch). Attach a repo and the Task becomes a Repo Task that opens a PR; leave it off and it's a Standalone Task that runs the agent in an isolated pod with no git checkout.

From the Dashboard

The fastest way to create a Task is through the web UI.

1. Navigate to Tasks → New Task.
2. At the top of the form, pick Repo Task (opens a PR) or Standalone Task (runs without a PR). The outcome banner underneath makes it explicit.
3. Choose Run now or Schedule. Scheduled Tasks become reusable blueprints — each trigger firing spawns a fresh run.
4. Fill in the title (becomes the PR title and branch name for Repo Tasks) and prompt. Prompts support {{param}} substitution on scheduled/webhook firings.
5. Pick an agent (Claude Code, Codex, Copilot, Gemini, OpenCode).
6. For Repo Tasks, select the repository and branch. For Standalone, this section is hidden.
7. Click Start Task (or Save Schedule). The label adapts to the mode.

The task enters the queue and is picked up by the worker. Watch live logs in the task detail view.

From Task Templates

If you frequently create similar tasks, save them as templates. Templates store the repo, prompt, agent type, and metadata so you can create tasks with a single click.

1. Go to Templates in the sidebar
2. Create a template with your base prompt and settings
3. Click Run on any template to instantly create a task

From GitHub Issues

Optio can browse GitHub Issues from your connected repositories and turn them into tasks.

Manual Assignment

1. Navigate to the Issues view in the dashboard
2. Browse issues across all connected repos
3. Click Assign to Optio on any issue
4. Optio creates a task with the issue title as the task title and the issue body as the prompt

Automatic Sync

Configure a GitHub Issues ticket provider to automatically sync issues into Optio tasks. The ticket sync worker runs periodically and picks up new issues based on your filter configuration.

1. Go to Settings and configure a GitHub Issues ticket provider
2. Set the sync scope (labels, assignees, or all issues)
3. New matching issues are automatically created as tasks

From Linear

Optio integrates with Linear as a ticket provider, syncing Linear issues into tasks.

1. Add a Linear ticket provider in Settings
2. Configure your Linear API key and team/project scope
3. The ticket sync worker polls Linear for new issues matching your configuration
4. Matching issues are created as Optio tasks with the Linear issue title and description

From the API

Create tasks programmatically via the REST API. This is useful for CI/CD pipelines, chatbots, or custom integrations.

{
  "title": "Add email validation to signup form",
  "prompt": "Add client-side and server-side email validation to the signup form in src/components/SignupForm.tsx. Use Zod for schema validation. Show inline error messages below the input field.",
  "repoUrl": "https://github.com/acme/webapp",
  "repoBranch": "main",
  "agentType": "claude",
  "priority": 0
}

curl -X POST https://optio.example.com/api/tasks \
  -H "Content-Type: application/json" \
  -H "Cookie: optio_session=YOUR_SESSION_TOKEN" \
  -d '{
    "title": "Add email validation to signup form",
    "prompt": "Add client-side and server-side email validation...",
    "repoUrl": "https://github.com/acme/webapp",
    "agentType": "claude"
  }'

Task Fields

From Schedules

Create recurring tasks with cron-based schedules. Useful for regular maintenance like dependency updates, security audits, or documentation refreshes.

1. Go to Schedules in the sidebar
2. Create a schedule with a cron expression and task template
3. The schedule worker checks for due schedules and creates tasks automatically

Task Priority & Ordering

Tasks have an integer priority field where lower numbers mean higher priority. You can reorder tasks in two ways:

• Dashboard — drag-and-drop reordering in the task list
• API — POST /api/tasks/reorder with an array of task IDs in desired order

Bulk Operations

Manage multiple tasks at once:

• POST /api/tasks/bulk/retry-failed — retry all failed tasks at once
• POST /api/tasks/bulk/cancel-active — cancel all running and queued tasks

What Happens After Creation

Once created, a task flows through the task lifecycle:

1. Enters the queue (pending → queued)
2. Task worker provisions a repo pod or reuses an existing one
3. Agent runs in an isolated git worktree
4. Agent opens a PR and the task transitions to pr_opened
5. PR watcher monitors CI, reviews, and merge status
6. On merge: completed. On failure: retried automatically or manually

Next Steps