# Flags

> Double-dash shortcuts in any Pullfrog instruction that pick the model, effort, and timeout, or expand into your own text.

Flags are double-dash shortcuts you can put in any instruction Pullfrog reads. Built-in flags change how a run behaves, and custom flags expand into text you define.

```text
@pullfrog fix the flaky checkout test --opus --timeout=2h
```

## Where flags are read

Pullfrog assembles each run's instructions from these levels, most general first:

1. **Org standing instructions** — every repository in the organization
2. **Repo standing instructions** — every run in the repository
3. **Mentions instructions** — runs started by an `@pullfrog` mention
4. **The per-run request** — your `@pullfrog` prompt, or the triggering automation's instructions when you did not tag Pullfrog

The standing levels are always added to the run. The per-run level is one or the other: when you tag `@pullfrog`, your prompt is the request and the automation's instructions do not apply.

Flags resolve when Pullfrog starts a run from a GitHub event. A [custom workflow](https://pullfrog.com/docs/custom-workflows) that passes a raw prompt skips this resolution, so configure it with the action's inputs.

## Custom flags (aliases)

A custom flag is a text alias: define `--refactor` once, and every occurrence expands in place to its replacement text. Use one for any snippet you repeat, such as a refactoring checklist or a review rubric.

```text
--mini  →  --model=anthropic/claude-haiku
--ship  →  --opus --notimeout
```

Aliases expand before built-in flags resolve, so an alias can contain built-in flags: `@pullfrog fix the flaky test --ship` runs on Claude Opus with no timeout. Expansion is a single pass, so an alias inside an alias's text is not expanded again.

To create one:

1. Open **Agent → Flags** in a repository's console. For an organization-wide flag, open the organization console and expand **Advanced**.
2. Click **Add flag**, enter the **Flag** name without the dashes, such as `refactor`, and enter the **Replacement text**.

A repo flag shadows an org flag with the same name. A flag name starts with a letter and contains letters, digits, underscores, and hyphens. Names are case-sensitive, so `--refactor` and `--Refactor` are different flags.

## Precedence

Built-in flags resolve last-occurrence-wins across all levels. Reading org, then repo, then the per-run request, the last value of a flag wins, so a more specific level overrides a more general one:

```text
org   --timeout=2h
repo  --timeout=30m
user  --notimeout      ← wins: this run has no timeout
```

Pullfrog removes built-in flags from the text before the agent sees it.

## Built-in flags

| Flag | Effect |
| --- | --- |
| [Model flags](https://pullfrog.com/docs/flags#model) | Pick the model for one run |
| [`--timeout`, `--notimeout`](https://pullfrog.com/docs/flags#timeout) | Change or remove the run timeout |
| [`--debug`](https://pullfrog.com/docs/flags#debug) | Raise the run's logging |
| [`--effort`](https://pullfrog.com/docs/flags#effort) | Set reasoning effort |
| [`--xrepo`](https://pullfrog.com/docs/cross-repo) | Let the run reach other repositories in the organization |

### Model

A model flag overrides the model for one run. Family flags resolve to the latest version of that model, on the repository's current provider when that provider carries it:

| Flag | Model |
| --- | --- |
| `--opus` / `--sonnet` / `--haiku` | Claude Opus / Sonnet / Haiku |
| `--fable` | Claude Fable (limited availability; needs Anthropic Fable access) |
| `--gpt` / `--codex` | GPT Sol |
| `--gpt-pro` / `--gpt-mini` | GPT Sol Pro / Luna |
| `--sol` / `--terra` / `--luna` | GPT Sol / Terra / Luna |
| `--gemini` / `--gemini-flash` | Gemini Pro / Flash |
| `--grok` | Grok |
| `--kimi` / `--kimi-k3` | Kimi K2 / K3 |
| `--deepseek` / `--deepseek-flash` | DeepSeek Pro / Flash |
| `--minimax` | MiniMax M2.5 |
| `--glm` | GLM |
| `--model=<slug>` | Any model slug, for example `--model=openrouter/claude-opus` |

Where a model flag is written decides how the run treats it:

- A model flag in your own `@pullfrog` prompt is an explicit request. When no provider key is configured, the OSS subsidy does not fund the model, or Pullfrog Router cannot serve it, the run fails before the agent starts with an error that names the fix.
- A model flag in org, repo, or automation instructions is a standing default, and the run treats it like the repository's own model setting.
- A `--model=` slug that Pullfrog does not recognize is left in the prompt as plain text.

### Timeout

| Flag | Effect |
| --- | --- |
| `--timeout=<duration>` | Set the run timeout, for example `--timeout=30m` or `--timeout=1h30m` |
| `--notimeout` | Remove the timeout |

The default is 1 hour. A `timeout` input on the workflow step takes precedence over these flags.

### Debug

| Flag | Effect |
| --- | --- |
| `--debug` | Raise this run's logging so the workflow log shows what the agent and its harness did |

Use it when a run fails with nothing useful in the log. The log then records Pullfrog's debug output and each request to your model provider. The flag changes only what the run logs, never what the agent may do, and applies only to the run you put it on.

> Debug logs are verbose and visible to anyone who can read your repository's Actions logs. Turn debugging on for the run you are diagnosing, then off again.

The workflow input does the same for every run of that workflow:

```yaml
- uses: pullfrog/pullfrog@v0
  with:
    debug: enabled
```

### Effort

| Flag | Effect |
| --- | --- |
| `--effort=<level>` | Set reasoning effort: `low`, `medium`, `high`, `xhigh`, `max`, or a position from `0` to `1` such as `0.75` |

Higher effort reasons longer and costs more; lower effort finishes faster. Models name and count their levels differently, so `--effort` sets a position on the running model's own range: `low` is its lowest level and `max` its highest. A level between two of the model's levels rounds down. The repository's [effort setting](https://pullfrog.com/docs/models#reasoning-effort) is the default.

Like every built-in flag, `--effort=medium` in repo instructions is a standing default that a per-run `--effort=max` overrides. An alias can wrap it:

```text
--deep  →  --effort=max
```
