Creating Tasks

Tasks are the primary unit of work in Optio. Each task represents a single agent run against a repository — the agent reads the prompt, writes code, and opens a pull request. You can create tasks from multiple sources.

From the Dashboard

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

1. Navigate to Tasks → New Task
2. Select the target repository from the dropdown
3. Enter a title — this becomes the branch name and PR title
4. Write a description — this is the prompt the agent receives. Be specific about what to implement, where to make changes, and any constraints
5. Optionally set priority (lower number = higher priority)
6. Click Create Task

The task enters the queue and is picked up by the task worker. You can watch live logs in the task detail view as the agent works.

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