Run (Standalone Task Execution)

Updated on Oct 1, 2026

frg run executes an ad-hoc task in your codebase without an issue, pull request, or ticket. Use it for small, focused changes that do not need the structured issue workflow. Unlike frg ask, which only answers questions, frg run can modify files and run commands.

Prerequisites

A valid Telerik license. See Licensing.
A supported coding agent, installed and authenticated. Check it with frg status.
No Issue ID, PR ID, or Ticket ID is required.
A clean working tree is recommended, so you can review the agent's changes with git diff.

Subcommands at a glance

frg run has no subcommands. It reads a task from one of three sources and writes to a fixed directory.

Command	What it does	Typical inputs	Outputs	Default role
`frg run`	Executes a task that can modify files and run commands	`TASK` argument, `--task-file <FILE>`, or `.forge/work/run/task.md`	Changes in your project; `.forge/work/run/task.md`, `.forge/work/run/summary.md`	`software_engineer`

Task input precedence:

text

TASK argument ──► --task-file <FILE> ──► .forge/work/run/task.md

Typical flow

text

write task ──► frg run ──► review summary.md + git diff ──► frg run --retry (if needed) ──► commit

Describe a multi-step task in a file:

bash

cat > improvements.md << 'EOF'
Refactor the cache module to use async/await.
- Keep the public API unchanged.
- Update the existing unit tests.
EOF

Run it:

bash

frg run --task-file improvements.md

Review the result:

bash

cat .forge/work/run/summary.md
git diff

If outputs are missing, continue the same session:

bash

frg run --retry "Also update the README usage example"

frg run

text

frg run [OPTIONS] [TASK]

Option	Description	Default
`[TASK]`	Task to execute. If omitted, Forge uses `--task-file` or `.forge/work/run/task.md`.	None
`--task-file <FILE>`	Reads task instructions from a plain-text or Markdown file.	None
`-a, --agent <NAME>`	Coding agent for this run. The `frg run` help lists `github_copilot` and `opencode`.	Agent in `agents.toml`
`-r, --role <ROLE>`	Overrides the default role: `product_manager`, `software_engineer`, `software_architect`, `technical_writer`, `security_analyst`, `sre`. Cannot be combined with `--custom-agent`.	`software_engineer`
`--custom-agent <NAME>`	Selects a custom agent configuration inside your coding agent. Cannot be combined with `--role`.	None
`-m, --model <MODEL>`	Overrides the model configured in `agents.toml`.	Model in `agents.toml`
`-c, --context-file <FILE>`	Adds a file path as context. Repeatable.	None
`--context-dir <DIR>`	Adds a directory as context. Repeatable. Up to 100 files per directory and 1 MB per file; binary files and hidden directories are skipped.	None
`--clear`	Clears the existing agent session and starts fresh.	Off
`--retry [<INSTRUCTIONS>]`	Continues the previous session to complete missing outputs. Requires an existing session; cannot be combined with `--clear`.	Off
`--auto-retry`	Retries once, in the same session, when expected outputs are missing.	Off
`--print-prompt`	Prints the compiled prompt without running the agent.	Off
`--tail`	Follows agent execution output in real time.	Off
`--bypass-safety-checks`	Skips prompt-injection validation. Bypasses are logged. See Prompt Safety.	Off
`-q, --quiet`	Suppresses all output except errors.	Off

Examples:

bash

# Inline task
frg run "Add input validation to the login form"

# Task from a file, with extra context
frg run --task-file my-refactoring.md --context-file docs/architecture.md

# Task from the default file
echo "Add tests for the date parser" > .forge/work/run/task.md
frg run

Notes:

Outputs go to the fixed directory .forge/work/run/, regardless of any Issue ID or Ticket ID in the context. frg --tail --continue also follows frg run trace files.
Whether Forge commits the changes follows your commit configuration. See Commit Behavior.
Use --print-prompt to check what the agent will receive before it changes files.

Run (Standalone Task Execution)

Prerequisites

Subcommands at a glance

Typical flow

frg run

See Also