Flags - Pullfrog
Skip to main content
Flags are double-dash shortcuts (--xrepo, --opus, --timeout=30m, --refactor) you can drop into any instruction Pullfrog reads. Some are custom aliases you define for reusable text; others are built-in flags that change how a run behaves (model, timeout, cross-repo access). All of them resolve through one leveled pass so the most specific instruction wins.

​
Where flags are read

Pullfrog assembles instructions from three levels, most general first:
  1. Org instructions — apply to every repo in the organization
  2. Repo instructions — apply to every run in the repository
  3. The per-run request — your @pullfrog prompt when you tagged Pullfrog, otherwise the trigger’s fallback instructions (most specific)
Standing prose from the org and repo levels is always added to the run. The per-run level is one channel or the other: tagging @pullfrog makes your prompt the request, and the trigger’s fallback instructions don’t apply. Flags and standing instructions resolve when Pullfrog dispatches a run from a GitHub event. Runs you trigger directly with a raw prompt (the headless action) bypass this resolution — configure those runs through the action’s own inputs instead.

​
Custom flags (aliases)

A custom flag is a bash-style text alias: define --tag once, and every occurrence expands inline to its replacement text. Use them for reusable snippets — a --refactor that expands to your refactoring checklist, a --security that pastes your review rubric. Custom flags can be defined at the org level (available to every repo) and the repo level (a repo alias shadows an org alias with the same name). The tag must start with a letter and may contain letters, numbers, underscores, and hyphens. Tags are case-sensitive — --refactor and --Refactor are different flags. Because aliases expand before built-in flags resolve, an alias whose text contains a built-in flag just works: 
--mini  →  --model=anthropic/claude-haiku
--ship  →  --opus --notimeout
So @pullfrog fix the flaky test --ship runs on Claude Opus with no timeout. Expansion is single-pass: an alias that expands to another alias is not re-expanded.

​
Creating a flag

  1. Open your repository (or organization) in the Pullfrog console
  2. Scroll to the Flags section
  3. Click Add flag
  4. Enter a tag (e.g. refactor) and the replacement text

​
Precedence

Built-in flags resolve last-occurrence-wins across the whole leveled stack. Reading org → repo → per-run request left to right, the last value of a given flag wins, so a more specific level always overrides a more general one: 
org   --timeout=2h
repo  --timeout=30m
user  --notimeout      ← wins: this run has no timeout
Built-in flags are stripped from the prose before it reaches the agent — they configure the run, they aren’t part of the prompt.

​
Built-in flags

​
Model

Override the model for a single run. Family flags resolve to the latest version of that model and inherit your repo’s current provider when possible:
A model flag in your own @pullfrog prompt is an explicit request: if the run can’t serve it (no provider key, not funded by an OSS subsidy, or not servable by Pullfrog Router) the run fails fast with an actionable error instead of silently downgrading. A model flag in org/repo instructions or a trigger’s fallback instructions is a standing default — if it’s unavailable, the run quietly falls back to a free model so it still produces value.

​
Timeout

FlagEffect
--timeout=<duration>Set a custom run timeout, e.g. --timeout=30m, --timeout=1h30m
--notimeoutDisable the timeout entirely
The default is 1 hour. The repo’s timeout setting is the repo-level default and resolves into the leveled stack like any other flag.

​
Cross-repo

--xrepo lets one run read and open PRs across multiple repositories in the same organization. See Cross-repo below.

​
Cross-repo

By default a run only touches the repository it was triggered from. --xrepo widens that to a bounded set of repos in the same organization.
Cross-repo access is always bounded by the triggering user’s own GitHub permissions — --xrepo can never let a run touch a repo the person triggering it couldn’t already touch. Each secondary repo is granted the narrowest access the user has: read-only repos are reference-only (clone and inspect, no PRs); repos the user can write to accept branches and pull requests. Because a bare --xrepo needs the triggerer’s identity to resolve, the value form --xrepo=a,b is the recommended org-wide default — it resolves without per-user OAuth and keeps token scope tight. During a cross-repo run the agent uses list_repos to see what’s in scope and checkout_repo to clone a secondary, then passes repo: "<name>" to the git and pull-request tools to act inside it. You can steer cross-repo work with two org-level settings: an xrepo brief (operator prose describing how your repos relate) and xrepo learnings (structural knowledge Pullfrog curates over time). See Learnings.