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.

Optio supports two AI agent backends: Claude Code (Anthropic) and OpenAI Codex. You select the agent when creating a task or set a default per-repository. Each backend has its own authentication and configuration options.

​
Claude Code

Claude Code is the default agent in Optio. It supports three authentication modes.

​
Authentication modes

The simplest mode. Requests are billed directly to your Anthropic account.
  1. Get an API key from console.anthropic.com.
  2. In Optio, go to Settings → Secrets and add a secret named ANTHROPIC_API_KEY with your key as the value.
  3. Add a secret named CLAUDE_AUTH_MODE with the value api-key.
Optio injects ANTHROPIC_API_KEY as an environment variable into each agent pod.
Optio reads credentials directly from the host machine’s macOS Keychain or ~/.claude/.credentials.json. This only works when the Optio API server runs on your local machine — it does not work in Kubernetes.Set CLAUDE_AUTH_MODE to max-subscription. No API key secret is required.
This mode is legacy and intended for local development only. For any deployed environment, use API key or OAuth token mode instead.

​
Model and performance settings

These settings are configured per-repository in Repos → [repo] → Settings.
SettingDescriptionDefault
ModelWhich Claude model to use (e.g., claude-sonnet-4-5, claude-opus-4-5). Enter the model ID as shown in the Anthropic documentation.—
Context windowContext window size in tokens. Leave blank to use the model default.—
Extended thinkingEnables Claude’s extended thinking mode for harder problems.Disabled
Effort levelThinking effort: low, medium, or high. Only relevant when extended thinking is enabled.—
Max turns (coding)Maximum agent conversation turns per coding task. Leave blank to use the global default. Lower values reduce cost.null (global default)
Max turns (review)Maximum turns for review subtasks. Leave blank to use the global default.null (global default)

​
Prompt templates

The system prompt sent to the agent is rendered from a template. You can customize the global default or set a per-repository override.

​
Where prompts are configured

  • Global default: Settings → Prompt templates — applies to all repositories that do not have an override.
  • Per-repository override: Repos → [repo] → Settings → Prompt template — takes precedence over the global default for that repository.

​
Template variables

The following variables are replaced when the template is rendered:
VariableValue
{{TASK_FILE}}Path to .optio/task.md inside the worktree — the file containing the full task description
{{BRANCH_NAME}}The git branch the agent is working on (e.g. optio/task-abc123)
{{TASK_ID}}The Optio task UUID
{{TASK_TITLE}}The task title
{{REPO_NAME}}The repository full name (e.g. acme/backend)
{{AUTO_MERGE}}true if auto-merge is enabled for the repository, otherwise false

​
Conditional blocks

You can show or hide sections of the prompt based on a variable’s value: 
{{#if AUTO_MERGE}}
When your changes are complete, open a PR. It will be merged automatically once CI passes.
{{else}}
When your changes are complete, open a PR and request a review.
{{/if}}
A variable is considered truthy if it is non-empty, not false, and not 0.

​
The task file

The task title and description are written to .optio/task.md inside the agent’s git worktree before the agent starts. The default prompt template instructs the agent to read this file first. This keeps the prompt short while allowing arbitrarily long task descriptions.

​
Example template

You are an expert software engineer working on {{REPO_NAME}}.

Read the task description at {{TASK_FILE}} before starting.

Requirements:
- Write clean, well-tested code.
- Follow existing conventions in the codebase.
- Open a pull request when your work is complete.

{{#if AUTO_MERGE}}
The PR will be merged automatically once CI passes — no need to request reviewers.
{{/if}}

Build docs developers (and LLMs) love

Get started for freeTalk to us