$ show jonwiggins/optio
Optio is a self-hosted, Kubernetes-native orchestration platform for AI coding agents (Claude Code, OpenAI Codex, GitHub Copilot, Gemini, Cursor, OpenCode). In production it runs three task tiers — repo tasks (issue/request → agent pod → PR), standalone jobs (parameterized agent runs without repo checkout), and persistent agents (long-lived, message-driven agents with turn-based execution) — plus an autonomous PR review loop. The core loop is driven by ~15 BullMQ workers (task, PR watcher, review, webhook, ticket sync, reconcile, workflow trigger) against a Postgres database, with Redis pub/sub powering a real-time event bus and WebSocket log/terminal/chat streaming to the Next.js dashboard and CLI. Agents execute in ephemeral pods built from per-language Docker images; a K8s-style reconciliation control plane (world snapshot + pure decision functions + CAS-gated executor) converges four run kinds and catches drift. The architecture is a pnpm/turbo monorepo: a Fastify 5 API with Drizzle ORM and Zod-validated OpenAPI schemas; a Next.js 15 admin dashboard (tasks, jobs, reviews, sessions, agents, cluster, analytics); a Commander-based CLI (login, task/repo/session/secret commands over REST + WebSocket); and a static docs site. Shared packages provide a clean AgentAdapter interface (`validateSecrets` → `buildContainerConfig` → `parseResult`), a Docker/Kubernetes container runtime abstraction, ticket provider adapters (GitHub, GitLab, Jira, Linear, Notion), and shared types/utilities (task state machines, repo URL parsing, SSRF guards, cost arithmetic). Workspace-scoped multi-tenancy with admin/member/viewer RBAC, AES-256-GCM secret encryption with AAD binding, WebSocket upgrade tokens, HMAC-signed internal calls, and a security-focused audit trail (optio_actions) are enforced throughout. Engineering strengths: the test suite is unusually thorough for a project this size — nearly every route, service, worker, and shared utility has a unit test, with per-file Postgres/Redis isolation for integration tests, real-server E2E tests using a deterministic fake container runtime (with mock directives like [[mock:pr]]), and Playwright smoke tests. The reconcile pattern, generic state machine utilities, and pure decision functions in `packages/shared/src/reconcile/` are the highest-craftsmanship code. Known debt: five near-duplicate NDJSON event parsers (one per agent, with drift risk), hardcoded model pricing tables in the Codex/Gemini adapters, scattered duplicated workspace-scoping checks, a 60+ file migration history with historical prefix collisions (now script-enforced), and raw SQL in the analytics service. The project moves fast (v0.1 → v0.4.1 within months, last commit 2026-08) and some surface area (OpenCode/OpenClaw adapters, skills marketplace) is explicitly experimental, but the core architecture is coherent and production-oriented.
The LLM identified 6 files worth highlighting for reuse:
Generic directed-acyclic-graph utilities: cycle detection, topological sort, and transitive dependent resolution. Sits under Optio's task dependency system but imports nothing internal — a pure, self-contained graph library that can be lifted into any project needing DAG-based scheduling, build ordering, or dependency validation.
Two-layer server-side request forgery guard: synchronous hostname/IP validation against private-CIDR blocklists plus an asynchronous DNS rebinding check that re-validates the resolved address. Applied uniformly to webhook URLs, ticket-provider hosts, and connection endpoints. This is non-obvious security engineering (DNS rebinding is rarely handled correctly) and is fully isolated, making it a drop-in guard for any service that fetches user-supplied URLs.
A minimal, typed, generic state machine exposing canTransition, transition, and isTerminal. It backs task lifecycle, workflow run, and persistent-agent state logic across the API and shared packages. Zero internal dependencies and no I/O — a clean, reusable building block for any event-driven system that needs guarded state transitions and terminal-state detection.
String-based decimal addition (addCostStrings) used to accumulate per-task USD costs without floating-point drift. Small but demonstrates correct reasoning about money representation — storing cost_usd as strings in the DB and summing via integer-scaled arithmetic. Directly reusable in any cost/billing aggregation code where float precision matters.
Pure K8s-style reconcile decision function: given a world snapshot and the desired run spec, it deterministically returns a list of actions to converge reality to intent (provision, retry, time out, mark done). I/O-free by design, making it trivially unit-testable, and it is the reference implementation of the reconcile-pattern that Optio extends to repo tasks, PR reviews, and persistent agents. The pattern itself — pure decision function + snapshot + CAS-gated executor — is a transferable architecture for any background worker with stateful resources.
Robust git remote URL parser and normalizer handling SSH shorthand (git@host:org/repo.git), HTTPS variants, .git suffixes, and case-insensitive host comparison. Pair with normalize-repo-url.ts for canonical form. Fully isolated string logic that any CI tool, CLI, or backend consuming git remotes can reuse to avoid the classic edge-case bugs in repo URL handling.