> ## 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.

# AI Agents

> Configure Claude Code or OpenAI Codex as the AI agent backend, including authentication, model settings, and prompt templates.

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.

<Tabs>
  <Tab title="Claude Code">
    ## Claude Code

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

    ### Authentication modes

    <AccordionGroup>
      <Accordion title="API key (pay-per-use)">
        The simplest mode. Requests are billed directly to your Anthropic account.

        1. Get an API key from [console.anthropic.com](https://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.
      </Accordion>

      <Accordion title="OAuth token (recommended for Kubernetes)">
        Uses your Claude Max or Pro subscription instead of API billing. The token is extracted from your local macOS Keychain once and stored encrypted in Optio's secrets store, where it is injected into agent pods.

        1. On a Mac where you are signed in to Claude, run the one-liner shown in the Optio setup wizard to extract your OAuth token.
        2. Paste the token into **Settings → Secrets** as a secret named `CLAUDE_CODE_OAUTH_TOKEN`.
        3. Add a secret named `CLAUDE_AUTH_MODE` with the value `oauth-token`.

        <Tip>
          OAuth token mode is the recommended approach for production Kubernetes deployments. It gives the agent full subscription access, supports usage tracking, and does not require the API server to have access to your local Keychain.
        </Tip>
      </Accordion>

      <Accordion title="Max subscription (local dev only)">
        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.

        <Warning>
          This mode is legacy and intended for local development only. For any deployed environment, use API key or OAuth token mode instead.
        </Warning>
      </Accordion>
    </AccordionGroup>

    ### Model and performance settings

    These settings are configured per-repository in **Repos → \[repo] → Settings**.

    | Setting                | Description                                                                                                                           | Default               |
    | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
    | **Model**              | Which 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 window**     | Context window size in tokens. Leave blank to use the model default.                                                                  | —                     |
    | **Extended thinking**  | Enables Claude's extended thinking mode for harder problems.                                                                          | Disabled              |
    | **Effort level**       | Thinking 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) |
  </Tab>

  <Tab title="OpenAI Codex">
    ## OpenAI Codex

    ### Authentication

    1. Get an API key from [platform.openai.com](https://platform.openai.com).
    2. In Optio, go to **Settings → Secrets** and add a secret named `OPENAI_API_KEY`.

    Optio also requires `GITHUB_TOKEN` to be set so the agent can open pull requests.

    ### Settings

    Codex settings are configured per-repository in **Repos → \[repo] → Settings**.

    | Setting                | Description                                                                 | Default               |
    | ---------------------- | --------------------------------------------------------------------------- | --------------------- |
    | **Effort level**       | Controls how much compute the model uses: `low`, `medium`, or `high`        | —                     |
    | **Max turns (coding)** | Maximum agent turns before stopping. Leave blank to use the global default. | null (global default) |
    | **Max turns (review)** | Maximum turns for review subtasks. Leave blank to use the global default.   | null (global default) |
  </Tab>
</Tabs>

***

## 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:

| Variable          | Value                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `{{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:

```text theme={null}
{{#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

```text theme={null}
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}}
```