Under the hood, all task and pod state changes flow through a Kubernetes-style reconciliation control plane — a pure-decision-plus-CAS-executor loop with periodic resync that keeps runs from getting stuck on lost events.

How It Works

Repo Tasks — ticket to merged PR

You create a task          Optio runs the agent           Optio closes the loop
─────────────────          ──────────────────────         ──────────────────────

  GitHub Issue              Provision repo pod             CI fails?
  Manual task       ──→     Create git worktree    ──→       → Resume agent with failure context
  Linear / Jira / Notion    Run Claude / Codex / Copilot   Review requests changes?
                            Open a PR                        → Resume agent with feedback
                                                           CI passes + approved?
                                                             → Squash-merge + close issue

1. Intake — tasks come from the web UI, GitHub Issues (one-click assign), Linear, Jira, or Notion
2. Provisioning — Optio finds or creates a Kubernetes pod for the repo, creates a git worktree for isolation
3. Execution — the AI agent (Claude Code, OpenAI Codex, or GitHub Copilot) runs with your configured prompt, model, and settings
4. PR lifecycle — Optio polls the PR every 30s for CI status, review state, and merge readiness
5. Feedback loop — CI failures, merge conflicts, and review feedback automatically resume the agent with context
6. Completion — PR is squash-merged, linked issues are closed, costs are recorded

Standalone Tasks — reusable agent work without a repo

You define a task           Optio triggers it              Optio runs & tracks
────────────────────        ─────────────────              ───────────────────

  Prompt template           Manual (UI / API)              Provision isolated pod
  {{PARAM}} variables  ──→  Cron schedule          ──→     Execute agent with params
  Agent + model config      Webhook from external          Stream logs in real time
  Budget & retry limits     Ticket events                  Track cost & token usage
                                                           Auto-retry on failure

Standalone Tasks run an agent in an isolated pod with no git checkout. Define a prompt template with {{PARAM}} placeholders, configure triggers (manual, cron schedule, webhook, or ticket), and let Optio handle execution, retries, and cost tracking. Repo Tasks can also be saved as blueprints with the same trigger types — see docs/tasks.md.

Connections — extend agent capabilities

Connections give your agents access to external tools and data at runtime. Configure a provider once, assign it to repos or agents, and Optio injects MCP servers into agent pods automatically.

Built-in providers: Notion, GitHub, Slack, Linear, PostgreSQL, Sentry, Filesystem, plus custom MCP servers and HTTP APIs.

Key Features

• Autonomous feedback loop — auto-resumes the agent on CI failures, merge conflicts, and review feedback; auto-merges when everything passes
• Repo Tasks and Standalone Tasks — one Task concept, two pipelines. Repo Tasks land code via PRs; Standalone Tasks run agents in empty pods for reports, triage, and ops. Both share triggers (manual / schedule / webhook / ticket), templates, and the unified /api/tasks HTTP layer
• Connections — plug external services (Notion, Slack, Linear, GitHub, PostgreSQL, Sentry, custom MCP servers) into agent pods with fine-grained access control per repo and agent type
• Pod-per-repo architecture — one long-lived Kubernetes pod per repo with git worktree isolation, multi-pod scaling, and idle cleanup
• Code review agent — automatically launches a review agent as a subtask, with a separate prompt and model
• Multi-agent support — run Claude Code, OpenAI Codex, GitHub Copilot, Google Gemini, or OpenCode with per-repo model and prompt configuration
• GitHub Issues, Linear, Jira, and Notion intake — assign issues to Optio from the UI or via ticket sync
• Reconciliation control plane — K8s-style pure-decision-plus-CAS-executor loop with periodic resync; keeps tasks and pods from getting stuck on lost events. Ships in shadow mode behind a feature flag
• Real-time dashboard — live log streaming, pipeline progress, cost analytics, and cluster health

Architecture

┌──────────────┐     ┌────────────────────┐     ┌───────────────────────────┐
│   Web UI     │────→│    API Server      │────→│      Kubernetes           │
│   Next.js    │     │    Fastify         │     │                           │
│   :3100      │     │                    │     │  ┌── Repo Pod A ───────┐  │
│              │←ws──│  Workers:          │     │  │ clone + sleep       │  │
│  Dashboard   │     │  ├─ Task Queue     │     │  │ ├─ worktree 1  ⚡    │  │
│  Tasks       │     │  ├─ PR Watcher     │     │  │ ├─ worktree 2  ⚡    │  │
│  Repos       │     │  ├─ Workflow Queue │     │  │ └─ worktree N  ⚡    │  │
│  Standalone  │     │  ├─ Reconciler     │     │  └─────────────────────┘  │
│  Connections │     │  ├─ Health Mon     │     │  ┌── Standalone Pod ────┐ │
│  Cluster     │     │  └─ Ticket Sync    │     │  │ isolated agent  ⚡    │ │
│  Costs       │     │                    │     │  └─────────────────────┘  │
│              │     │  Services:         │     │                           │
│              │     │  ├─ Repo Pool      │     │                           │
│              │     │  ├─ Workflow Pool  │     │  MCP servers injected via │
│              │     │  ├─ Connections    │     │  Connections at runtime    │
│              │     │  ├─ Review Agent   │     │                           │
│              │     │  └─ Auth/Secrets   │     │                           │
└──────────────┘     └─────────┬──────────┘     └───────────────────────────┘
                               │                  ⚡ = Claude / Codex / Copilot / Gemini
                        ┌──────┴──────┐
                        │  Postgres   │  Tasks, workflows, connections, logs, secrets
                        │  Redis      │  Job queue, pub/sub, live streaming
                        └─────────────┘

Task lifecycle

  ┌──────────────────────────────────────────────────┐
  │                     INTAKE                       │
  │                                                  │
  │   GitHub Issue ───→ ┌──────────┐                 │
  │   Manual Task ───→  │  QUEUED  │                 │
  │   Ticket Sync ───→  └────┬─────┘                 │
  └───────────────────────────┼──────────────────────┘
                              │
  ┌───────────────────────────┼──────────────────────┐
  │                 EXECUTION ▼                      │
  │                                                  │
  │   ┌──────────────┐    ┌─────────────────┐        │
  │   │ PROVISIONING │───→│     RUNNING     │        │
  │   │ get/create   │    │  agent writes   │        │
  │   │ repo pod     │    │  code in        │        │
  │   └──────────────┘    │  worktree       │        │
  │                       └───────┬─────────┘        │
  └───────────────────────────────┼──────────────────┘
                                  │
                ┌─────────────┐   │   ┌──────────────────┐
                │   FAILED    │←──┴──→│    PR OPENED     │