Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jonwiggins/optio/llms.txt

Use this file to discover all available pages before exploring further.

A repository in Optio represents a GitHub repository that your agents will work on. Each repository has its own isolated pod environment and a full set of configuration options — model selection, prompt templates, concurrency limits, review settings, and more — so you can tune agent behavior per project.

​
Adding a repository

1

Open the Repositories page

Navigate to Repositories in the sidebar and click Add Repository.
2

Enter the repository URL

Paste the GitHub repository URL (e.g., https://github.com/your-org/your-repo). Optio normalizes the URL to a canonical HTTPS form for consistent matching.
3

Auto-detect configuration

Optio queries the repository’s root files to detect the language ecosystem and test command. For example, a package.json selects the Node.js container image and sets npm test as the test command. A Cargo.toml selects the Rust image and sets cargo test. You can override any detected setting after the repository is added.
4

Save and configure

Click Add Repository. The repository is saved with sensible defaults. Open the repository’s Settings tab to fine-tune any configuration options.

​
Configuration options

Default branch — The branch the agent checks out as the base for new worktrees. Defaults to main. Change this if your repository uses master or a different integration branch.Agent model — The Claude model used for coding tasks on this repository. Enter the model ID as shown in the Anthropic or OpenAI documentation (e.g., claude-sonnet-4-5). Leave blank to use the global default.Prompt template — The system prompt the agent receives before reading the task file. If left blank, the global default prompt template is used. Override this field to give the agent repository-specific context: conventions, architecture notes, testing requirements, or anything else relevant to this codebase.
Image preset — The base container image used for the repository pod. Optio provides five presets:
PresetContents
nodeNode.js, npm, pnpm, yarn
pythonPython 3, pip, uv
goGo toolchain
rustRust toolchain, Cargo
fullAll of the above
The base preset contains only the essentials (git, curl, common CLI tools) and is used as a fallback when no language is detected.Test command — The command Optio passes to the review agent as {{TEST_COMMAND}}. Auto-detected from the repository root (e.g., npm test, cargo test, go test ./..., pytest). Override if your project uses a non-standard test invocation.
For repositories that need additional tooling, environment variables, or setup steps beyond what the base image provides, create a file at .optio/setup.sh in the repository root.This script runs inside the pod once after the repository is cloned, before any agent tasks execute. Use it to install extra packages, configure environment variables, set up language version managers, or run any other initialization.
#!/bin/bash
# .optio/setup.sh

# Install additional tools
npm install -g tsx

# Configure environment
cp .env.example .env
Because the pod uses a persistent volume, packages installed in .optio/setup.sh survive pod restarts. You only pay the setup cost once per pod lifecycle.
These three settings control how many tasks can run concurrently for this repository and how many pods back them.
SettingDefaultRangeDescription
Max concurrent tasks21–50Maximum tasks running simultaneously in this repository’s pod(s).
Max pod instances11–20Maximum number of pod replicas for this repository. Each pod gets its own persistent volume.
Max agents per pod21–50Maximum concurrent agent worktrees per pod instance.
Total capacity is Max pod instances × Max agents per pod. Increase Max pod instances when you need higher throughput and have sufficient cluster resources. For most repositories, the defaults are a good starting point.
Pods scale up dynamically when demand exceeds current capacity (up to the instance limit) and scale down by cleaning up idle pods after 10 minutes of inactivity.
Enable code review — When enabled, a review agent runs as a subtask after the coding agent opens a PR.Review trigger — Controls when the review agent launches:
  • on_ci_pass — The review agent runs only after all CI checks pass. This is the recommended setting: it avoids reviewing code that already has known failures.
  • on_pr — The review agent runs immediately when the PR is opened, before CI results are available.
Review model — The model used for the review agent. Enter a model ID (e.g., claude-sonnet-4-5). Defaults to the value of claudeModel for the repository. Using a lighter model here reduces cost while reserving a more capable model for coding tasks.Review prompt template — A custom prompt for the review agent. Supports the template variables {{PR_NUMBER}}, {{TASK_FILE}}, {{REPO_NAME}}, {{TASK_TITLE}}, and {{TEST_COMMAND}}. Leave blank to use the built-in default review prompt.Max turns (review) — Maximum number of agent turns during a review task. Leave blank to use the global default (10).
Auto-merge — When enabled, Optio squash-merges the PR automatically once CI passes and any review is approved. Disabled by default.Auto-resume — When enabled, Optio automatically re-queues the agent on CI failure, merge conflicts, or review feedback. Disabled by default.Auto-resume on review — When enabled, the agent is re-queued with the reviewer’s comments when a reviewer requests changes.Max auto-resumes — The maximum number of automatic resume cycles per task. After this limit, the task stays in needs_attention for manual intervention. Leave blank to use the global default (10).

Build docs developers (and LLMs) love

Get started for freeTalk to us