Flags

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.

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

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

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

FlagEffect
Model flagsPick the model for one run
--timeout, --notimeoutChange or remove the run timeout
--debugRaise the run's logging
--effortSet reasoning effort
--xrepoLet 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:

FlagModel
--opus / --sonnet / --haikuClaude Opus / Sonnet / Haiku
--fableClaude Fable (limited availability; needs Anthropic Fable access)
--gpt / --codexGPT Sol
--gpt-pro / --gpt-miniGPT Sol Pro / Luna
--sol / --terra / --lunaGPT Sol / Terra / Luna
--gemini / --gemini-flashGemini Pro / Flash
--grokGrok
--kimi / --kimi-k3Kimi K2 / K3
--deepseek / --deepseek-flashDeepSeek Pro / Flash
--minimaxMiniMax M2.5
--glmGLM
--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

FlagEffect
--timeout=<duration>Set the run timeout, for example --timeout=30m or --timeout=1h30m
--notimeoutRemove the timeout

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

Debug

FlagEffect
--debugRaise 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.

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

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

Effort

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

--deep  →  --effort=max
© 2026 Pullfrog, Inc.

On this page