Skip to content
/
Tier B A3 MCP-anchored

Optio

optio · jonwiggins/optio · ★ 967 · last commit 2026-05-07

Self-hosted Kubernetes-native AI engineering platform that orchestrates ticket-to-PR automation with automatic CI/review feedback loops, multi-vendor agent support, and persistent inter-agent messaging — code never leaves your infrastructure.

Best whenAI agent orchestration belongs in your Kubernetes cluster alongside your other infrastructure — not in someone else's cloud.
Skip ifsending source code to third-party AI services, vendor lock-in to a single agent provider
vs seeds
claude-conductoris a local session manager while Optio is a production pla…
Primitive shape 11 total
Subagents 4 MCP tools 7
00

Summary

Optio — Summary

Optio is a self-hosted Kubernetes-native AI engineering platform that orchestrates agent work through three tiers: Tasks (ticket-to-PR with feedback loop), Jobs (standalone parameterized agent runs), and Persistent Agents (long-lived message-driven services). Built on a Kubernetes-style reconciliation control plane (pure-decision + CAS-executor loop), Optio provisions pod-per-repo isolation with git worktree concurrency, auto-resumes agents on CI failures and review feedback, and squash-merges PRs when all checks pass. The web UI (Next.js, port 3100) provides real-time log streaming, pipeline progress, cost analytics, and cluster health; an API server (Fastify, port 30400) handles all orchestration. Multi-vendor agent support (Claude Code, OpenAI Codex, GitHub Copilot, Google Gemini, OpenCode) is configurable per repo. Persistent Agents communicate via inter-agent HTTP (/api/internal/persistent-agents/*) for direct and broadcast messaging. AES-256-GCM secrets at rest, OIDC/OAuth, Kubernetes RBAC, and audit-friendly task history make it enterprise-grade.

Differs from seeds: Optio is the only framework in the surveyed space that deploys entirely on Kubernetes with a formal reconciliation control plane; all seeds run locally or in CI processes. Unlike taskmaster-ai (which generates task lists) or claude-conductor (which orchestrates Claude sessions), Optio is a full infrastructure platform — closest architectural peer is a self-hosted Devin/Sweep, not a prompt-layer tool. The persistent agent tier with inter-agent messaging is unique among all 11 seeds.

01

Overview

Optio — Overview

Origin

Optio (jonwiggins/optio) is developed under MIT license, 7 contributors, 967 stars, 108 forks. Version v0.4.0, last release 2026-04-27, last commit 2026-05-07. Built with Next.js frontend, Fastify API backend, BullMQ/Redis for job queuing, Drizzle ORM, and Kubernetes for pod orchestration. Active project.

Philosophy

Optio's positioning is self-described as "CI/CD where the build step is an AI agent." The team explicitly cedes the simpler market ("if you'd ship to a hosted agent without thinking twice, the hosted options are simpler") and targets the security-conscious, Kubernetes-operating organization.

Three-tier model:

  • Tasks — ticket-to-PR with feedback loop (repo checkout, worktree, PR lifecycle)
  • Jobs — standalone parameterized agent runs (no repo, produces side effects)
  • Agents — long-lived message-driven processes (addressable by other agents)

Against Hosted Solutions

"Optio runs entirely in your infrastructure, behind whichever agent vendor you trust, against whichever Kubernetes cluster you already operate."

The pitch is data sovereignty and multi-vendor flexibility:

  • Code, secrets, and agent logs never leave your network
  • Multi-vendor agents: Claude Code, OpenAI Codex, GitHub Copilot, Google Gemini, OpenCode
  • Switch per repo, or A/B agents on the same task

Manifesto-Style Quotes

"The feedback loop is what makes Tasks different. When CI fails, the agent is automatically resumed with the failure context. When a reviewer requests changes, the agent picks up the review comments and pushes a fix. When everything passes, the PR is squash-merged and the issue is closed. You describe the work; Optio drives it to completion."

"If you'd ship to a hosted agent without thinking twice, the hosted options are simpler. If shipping your repo to someone else's cloud is a non-starter — Optio is built for you."

Reconciliation Control Plane

Optio's internal architecture uses a Kubernetes-style reconciliation pattern:

"A pure-decision-plus-CAS-executor loop with periodic resync that keeps runs from getting stuck on lost events."

This is a deliberate engineering choice borrowed from Kubernetes — pure decision functions (no side effects) that emit actions, applied by a CAS executor.

02

Architecture

Optio — Architecture

Distribution

  • Self-hosted on Kubernetes: Helm chart (helm/) + Docker Compose for development
  • No cloud version: Fully self-hosted only

Install (Development)

git clone https://github.com/jonwiggins/optio
cd optio
docker-compose up    # Postgres + Redis
# Then run API + Web separately

Directory Tree

apps/
  api/                    # Fastify API server
    src/
      db/                 # Drizzle ORM schemas
      routes/             # API routes
      schemas/            # Zod schemas
      services/           # Business logic (task, workflow, PA, repo pool)
      telemetry/          # OpenTelemetry
      plugins/            # Fastify plugins
  web/                    # Next.js frontend
    src/
      app/                # Next.js app router
      components/         # React components
      hooks/              # React hooks
      lib/                # Client utilities
  cli/                    # (implied, not confirmed)
  site/                   # Documentation site
docs/
  tasks.md, persistent-agents.md, reconciliation.md
examples/
  persistent-agents/
    forge/                # 4-agent demo (Vesper, Forge, Sentinel, Chronicler)
    mars-mission-control/
helm/                     # Helm chart
k8s/                      # Kubernetes manifests
Dockerfile.agent, Dockerfile.api, Dockerfile.optio, Dockerfile.web
docker-compose.yml

Tech Stack

Layer Technology
Web UI Next.js + React, port 3100
API server Fastify (Node.js), port 30400
Job queue BullMQ + Redis
Database PostgreSQL + Drizzle ORM
Agent pods Kubernetes (GKE, EKS, AKS)
Secrets AES-256-GCM at rest
Auth OIDC/OAuth + Kubernetes RBAC
Observability OpenTelemetry
Pub/sub Redis

Required Runtime

  • Kubernetes cluster (GKE, EKS, AKS, or any conformant K8s)
  • PostgreSQL
  • Redis
  • Docker (for agent pods)

Supported Git Platforms

  • GitHub
  • GitLab (including self-hosted via GITLAB_HOSTS)
  • AWS CodeCommit (via AWS access keys / IRSA)

Supported Agent Vendors

Per-repo configurable:

  • Claude Code
  • OpenAI Codex
  • GitHub Copilot
  • Google Gemini
  • OpenCode
03

Components

Optio — Components

API Server Workers

Worker Purpose
Task Queue (BullMQ) Processes repo task runs
PR Watcher Polls PR status every 30s
Workflow Queue Processes standalone job runs
PA Worker Persistent agent turn execution
Reconciler Kubernetes-style state reconciliation
Health Monitor Pod health checking
Ticket Sync GitHub/Linear/Jira/Notion integration
Connection Service MCP server injection into pods

API Routes (Unified /api/tasks layer)

Route Purpose
GET/POST /api/tasks Unified task list and creation
GET /api/tasks/:id Resolve task across all three types
POST /api/tasks/:id/runs Spawn task run
/api/jobs/* Standalone task alias
/api/task-configs/* Repo blueprint alias
/api/persistent-agents/* Persistent agent management
/api/internal/persistent-agents/* Inter-agent messaging

Persistent Agent Demo (The Forge)

Four-agent team example in examples/persistent-agents/forge/:

Slug Name Role
vesper Vesper Architect — receives feature requests, dispatches specs
forge Forge Implementer — receives specs, drafts code
sentinel Sentinel Reviewer — reviews PRs, posts findings
chronicler Chronicler Scribe — maintains running team journal

Messaging patterns: direct messages (Vesper→Forge), broadcasts (Forge→all), file-based handoff (Chronicler→journal).

Connections (MCP Integration)

Built-in providers injected into agent pods at runtime:

  • Notion, GitHub, Slack, Linear, PostgreSQL, Sentry, Filesystem
  • Custom MCP servers
  • HTTP APIs

Fine-grained access control per repo and agent type.

Task Types

Type What Where
Repo Task PR-producing agent run Repo pod + git worktree
Standalone Task (Job) Arbitrary agent in empty pod Isolated pod, no git
Persistent Agent Long-lived, message-driven Pod with lifecycle mode

Pod Lifecycle Modes (Persistent Agents)

Mode Behavior Cost/Latency
always-on Pod never idles Lowest latency, highest cost
sticky (default) Pod stays warm after turn for idle window Balanced
on-demand Cold-start every turn Lowest cost, highest latency

Prompt Templates

Reusable templates with {{param}} substitution and {{#if param}}...{{/if}} blocks. Stored in prompt_templates table with kind discriminator: prompt, review, job, task.

05

Prompts

Optio — Prompts

Prompt 1: CLAUDE.md (Agent Instructions)

Technique: Domain-model documentation as agent context — comprehensive Optio data model description

Verbatim excerpt from CLAUDE.md:

## What is Optio?

Think of it as "CI/CD where the build step is an AI agent." One primary user-facing 
concept (Tasks) with one attribute (has a repo) flipping the pipeline, plus shared primitives:

**Tasks** — a configured unit of agent work. A Task has a **Who** (agent type), **What** 
(prompt or template), **When** (trigger: manual / schedule / webhook / ticket), optional 
**Where** (repo + branch), and **Why** (description).

**Unified `/api/tasks` HTTP layer.** All three kinds are reachable through one polymorphic 
HTTP resource:
- GET /api/tasks?type=repo-task|repo-blueprint|standalone|all
- POST /api/tasks — body takes {type, ...}; dispatches to taskService, taskConfigService, 
  or workflowService based on type

Analysis: CLAUDE.md serves as the primary developer-context document for AI agents working on the Optio codebase itself. It documents internal naming conventions, API contracts, and backend-naming discrepancies (legacy table names vs. UI names). This is meta-use: Optio uses agents to develop Optio, and CLAUDE.md is the agent's project bible.

Prompt 2: Prompt Templates with {{param}} Substitution

Technique: Mustache-style parameterized prompt templates for reusable agent tasks

From CLAUDE.md:

**Templates** — reusable prompt templates in prompt_templates with a kind discriminator 
(prompt / review / job / task). Supports {{param}} substitution and {{#if param}}...{{/if}} 
blocks. Rendered lazily on trigger firing so params from the trigger payload substitute 
into the prompt.

Analysis: Optio's template engine supports conditional blocks via {{#if}}, enabling prompts that adapt to trigger context. Templates are stored in the database and rendered at runtime, enabling versioning and per-repo customization.

Prompt 3: Forge Multi-Agent Example

Technique: Role-specialized persistent agents with explicit messaging contracts

From examples/persistent-agents/forge/README.md:

| Slug | Name | Role |
|---|---|---|
| vesper | Vesper | Architect — receives feature requests, breaks them into specs, dispatches |
| forge | Forge | Implementer — receives specs, drafts code, reports back to Vesper |
| sentinel | Sentinel | Reviewer — receives PR-opened messages, runs review, posts findings |
| chronicler | Chronicler | Scribe — listens to broadcasts, maintains team journal |

Analysis: Each persistent agent has a system prompt (stored in DB) defining its role. The Forge demo demonstrates three messaging patterns: direct messages (Vesper→Forge), broadcasts (Forge→all), file-based handoff (Chronicler→journal). System prompts are version-controlled via the Optio DB; changing the prompt changes the agent's behavior.

09

Uniqueness

Optio — Uniqueness & Positioning

Differs From Seeds

Optio is categorically different from all 11 seeds. It is a full Kubernetes-native infrastructure platform for orchestrating AI agent work, not a prompt layer or skill pack. No seed deploys on Kubernetes, uses a reconciliation control plane, or provides a persistent inter-agent messaging bus. The closest seed is claude-conductor in orchestrating multiple Claude sessions, but claude-conductor is a local session manager while Optio is a production platform with Kubernetes pods, encrypted secrets, OIDC auth, and multi-vendor agent support. The persistent agent tier (long-lived, message-driven, addressable by other agents) has no equivalent in the seed set.

Distinctive Opinion

"CI/CD where the build step is an AI agent."

This framing is the most precise market positioning in the batch. Optio is not trying to be a better single-agent tool — it is building the orchestration layer that enterprise engineering teams would want: auditable, self-hosted, multi-vendor, Kubernetes-native.

The reconciliation loop (Kubernetes-style pure-decision-plus-CAS-executor) is an unusual engineering choice for an AI orchestration platform — borrowed from infrastructure engineering for operational correctness.

Positioning

  • Primary target: "security-conscious organizations", "regulated industries", "teams already running Kubernetes"
  • Against Devin, Charlie Labs, Sweep: "self-hosted = code never leaves your network"
  • Against vendor lock-in: multi-vendor (Claude Code, Codex, Copilot, Gemini, OpenCode)
  • Closest market peer: self-hosted Devin/Sweep (but MIT, open source)

Observable Failure Modes

  1. Kubernetes complexity barrier: Teams without K8s expertise cannot use Optio's primary deployment mode. Docker Compose is dev-only. This restricts the total addressable market.
  2. Cold-start latency: On-demand pod lifecycle mode has cold-start overhead that makes latency unpredictable for interactive tasks.
  3. Agent vendor API changes: When Claude Code, Codex, or Copilot change their CLI interfaces, Optio's agent execution layer requires updates. Multi-vendor support amplifies this maintenance surface.
  4. No prompt engineering layer: Optio provides infrastructure but minimal guidance on writing effective prompts or managing context quality. Teams must bring their own prompt engineering (or pair with a framework like AgentOps or OAC).
  5. AWS CodeCommit gaps: CodeCommit has no native CI or issues — getCIChecks returns [], auto-merge fires on checksStatus="none". CI gates are effectively bypassed for CodeCommit repos.

Cross-References

  • The Forge demo (Vesper+Forge+Sentinel+Chronicler) demonstrates multi-agent coordination patterns also seen in Liza (adversarial pairs) and AgentOps (council)
  • MCP Connections feature positions Optio as an orchestrator that can compose multiple MCP servers for each agent
  • Optio's PR auto-merge + CI feedback loop is the most complete implementation of the "agent as CI/CD step" pattern in the surveyed space
04

Workflow

Optio — Workflow

Task Lifecycle (Ticket to 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

Detailed Steps

  1. Intake: GitHub Issues (1-click assign), Manual, Linear, Jira, or Notion
  2. Provisioning: Optio finds/creates a Kubernetes pod for the repo; creates git worktree for isolation
  3. Execution: AI agent runs with configured prompt, model, settings; streams logs to UI
  4. PR lifecycle: Optio polls PR every 30s for CI status, review state, merge readiness
  5. Feedback loop: CI failures, merge conflicts, review feedback → automatically resume agent with context
  6. Completion: PR squash-merged, linked issues closed, costs recorded

Job Workflow (Standalone Tasks)

No git checkout. Runs agent in isolated pod with {{PARAM}} template substitution. Triggers: manual, cron schedule, webhook, ticket event.

Persistent Agent Lifecycle

Create agent (system prompt + lifecycle mode)
  ↓ Assign slug
  ↓ Wake on: user message | agent message | cron | webhook | ticket
  ↓ Execute one turn (drain inbox → render prompt → run agent → halt)
  ↓ Wait for next wake

Approval Gates

Optio automates the CI/review feedback loop but does not gate on human approval before execution. Human approval surfaces as:

  • PR reviewer approval (tracked by PR Watcher)
  • PR merge decision (auto-merge on CI pass + approval)
  • Task configuration (human sets up tasks/blueprints upfront)

Phase-to-Artifact Map

Phase Artifact
Intake Task record in tasks/task_configs/workflows table
Provisioning Kubernetes pod + git worktree
Execution Agent logs streamed to UI + PR opened
PR lifecycle CI check results, review comments
Feedback loop Resumed agent run with failure context
Completion Merged PR + closed issue + cost record

Reconciliation Loop

All state changes flow through the reconciler:

  • Pure decision function emits desired state
  • CAS (Compare-And-Swap) executor applies changes
  • Periodic resync prevents stuck runs from lost events
  • Four RunKinds: repo, standalone, pr-review, persistent-agent
06

Memory Context

Optio — Memory & Context

Persistent Storage (PostgreSQL)

Optio persists extensive state in PostgreSQL:

Table Content
tasks Repo task runs
task_configs Repo task blueprints
workflows Standalone job configs
workflow_runs Standalone job run records
workflow_triggers Polymorphic trigger table
persistent_agents Agent definitions (slug, system prompt, lifecycle mode)
persistent_agent_turns Per-turn execution records
persistent_agent_messages Agent inbox messages
persistent_agent_pods Pod allocation tracking
prompt_templates Reusable prompt templates
connections External service configs (MCP)

Agent Context at Execution

When a Task runs, Optio injects context:

  1. Configured prompt (from task config or template)
  2. MCP server connections (from assigned Connections)
  3. Git worktree (for repo tasks)
  4. Environment (secrets, credentials — AES-256-GCM encrypted at rest)

Cross-Session Memory (Persistent Agents)

Persistent Agents have durable identity:

  • System prompt is their persistent behavioral definition
  • Inbox accumulates messages between turns
  • Turn history records all executions
  • When re-woken, the PA renders its inbox into the prompt and executes one turn

This is the closest Optio comes to "memory" — the inbox is persistent conversation state.

Task History as Audit Log

Every task run produces:

  • Streamed agent logs (accessible via UI and WebSocket)
  • Cost and token breakdown per run
  • Pipeline stage progression (queued → running → PR → CI → review → merge)
  • Error records

This history is auditable — teams can review exactly what the agent did and what it cost.

No Cross-Task Context Inheritance

Tasks are isolated. One Task's agent output does not feed into another Task's agent context (unless explicitly configured via prompt templates that reference other tasks).

Persistent Agents are the exception: their inbox enables explicit cross-task context threading.

Secrets Management

Secrets are stored AES-256-GCM encrypted in PostgreSQL and injected into agent pods at runtime. Agents cannot exfiltrate secrets via pod logs (Optio controls the execution environment).

07

Orchestration

Optio — Orchestration

Multi-Agent Pattern

Hierarchical + persistent-service model

Three orchestration tiers:

  1. Repo Tasks: one-shot agent per worktree, code-review agent as optional subtask
  2. Jobs: isolated one-shot agents, no coordination
  3. Persistent Agents: long-lived processes with inter-agent messaging

Reconciliation Control Plane

The reconciler is the orchestration engine:

  • Pure decision function (no side effects) → emits desired state transitions
  • CAS executor applies transitions
  • Periodic resync prevents stuck states
  • Covers all four run kinds: repo, standalone, pr-review, persistent-agent

Persistent Agent Coordination

Persistent Agents coordinate via the inter-agent HTTP API:

POST /api/internal/persistent-agents/{slug}/messages  # direct message
POST /api/internal/persistent-agents/broadcast        # broadcast to all

The Forge demo uses three patterns:

  • Direct messages: Vesper → Forge (spec dispatch)
  • Broadcasts: Forge → all (PR-opened notification)
  • File-based handoff: Chronicler → journal file

Isolation Mechanism

Container + git-worktree — each task gets:

  • Dedicated Kubernetes pod (or pod pool slot) per repo
  • Git worktree within the pod for task isolation
  • Multiple worktrees can run concurrently per pod

Multi-Model

Yes — configurable per repo:

  • Different repos can use different agent vendors
  • A/B testing different agents on the same task is supported
  • Code review agent can use a different model than the main coder agent

No formal role-to-model mapping; configured at task/repo level.

Execution Modes

Tier Execution Mode
Repo Task One-shot (until PR opened) + event-driven resumption
Job One-shot
Persistent Agent Event-driven (wake-on-message/cron/webhook)

Feedback Loop

What makes Optio's Task execution distinctive:

  • CI failure → agent resumed with CI failure context
  • Merge conflict → agent resumed with conflict context
  • Review changes → agent resumed with reviewer feedback
  • All within the same task, no new task creation required

Max Concurrent Agents

Per-repo pod pool size is configurable. Multiple worktrees per pod enable concurrent task execution without pod proliferation.

08

Ui Cli Surface

Optio — UI / CLI Surface

No CLI Binary

Optio does not ship a user-facing CLI binary. Management is done through:

  • The web UI
  • The REST API (/api/tasks, etc.)
  • The Forge demo's setup shell scripts

Web Dashboard (Primary Surface)

  • Type: Web dashboard (full SPA)
  • Port: 3100 (Next.js frontend)
  • Tech stack: Next.js + React
  • API server port: 30400 (Fastify)

Navigation sections (from CLAUDE.md):

  • Run: Tasks · Jobs · Reviews · Issues · Scheduled
  • Live: Agents · Sessions
  • Library: Prompts · Repos · Connections

Dashboard features:

  • Overview — running tasks count, completed tasks, Claude Max usage, active pods, recent activity
  • Task detail — live-streamed agent logs, pipeline progress (queued → setup → running → PR → CI checks → review → merge → done), cost tracking per step
  • Agent management — persistent agent list, inbox, turn history
  • Cost analytics — per-task and aggregate cost/token tracking
  • Cluster health — pod status, scaling metrics
  • Connections — external service configuration (MCP)

Real-Time Features

  • WebSocket live log streaming from agent pods to browser
  • Pipeline progress bar with stage-by-stage status
  • PR tracking with CI check status embedded

Kubernetes / Helm Surface

# Helm install (simplified)
helm install optio ./helm \
  --set postgres.host=... \
  --set redis.host=...

Full Helm chart in helm/ with configurable:

  • Replica counts, resource limits
  • Ingress configuration
  • Secret management (K8s secrets)
  • RBAC configuration

Observability

  • OpenTelemetry instrumentation in API server (apps/api/src/telemetry.ts)
  • Task cost and token metrics
  • PR lifecycle timing
  • Pod health monitoring

Related frameworks

same archetype · same primary tool · same memory type

Taskmaster AI ★ 27k
A3 MCP-anchored

Converts a PRD into a dependency-ordered JSON task graph that AI coding agents execute one task at a time, eliminating context…

ccmemory ★ 1
A3 MCP-anchored

Accumulates decisions, corrections, and failed approaches from Claude Code sessions into a queryable Neo4j graph so each new…

Pimzino spec-workflow-mcp ★ 4.2k
A3 MCP-anchored

MCP server providing spec-driven development workflow with dashboard-backed approval gates, implementation logging, and VSCode…

MCP Shrimp Task Manager ★ 2.1k
A3 MCP-anchored

Convert natural language requests into structured AI development tasks with chain-of-thought enforcement, reflection gates, and…

Bernstein ★ 460
A3 MCP-anchored

Govern parallel CLI coding agents with a deterministic Python scheduler, HMAC-chained audit trail, and compliance-ready signed…

LeanSpec ★ 252
A3 MCP-anchored

Provides a unified spec CLI and MCP server over any existing spec backend (markdown, GitHub Issues, ADO), making spec-driven…