Modifiers

Updated on Oct 1, 2026

Modifiers are optional flags that change how a workflow operation runs without changing what it does. Use them to add your own instructions, request lighter output, or apply fixes. This page also covers the session, retry, context, and safety options that shape a run.

How modifiers work

Each modifier maps to a variant of the operation's task prompt, defined in the command configuration. For example, for frg issue draft:

Command	Task prompt
frg issue draft	issue_draft
frg issue draft --edit	issue_draft_edit
frg issue draft --lite	issue_draft_lite
frg issue draft --lite-edit	issue_draft_lite-edit

You can use only one modifier per run. Combining modifiers fails with:

text

Multiple modifiers specified: [...]. Only one modifier can be active at a time. Use combined modifiers like --lite-edit for specific use cases.

Modifier reference

Modifier	Value	Available on	Description
--edit	Optional instructions	issue draft, issue review, issue plan, backlog create, backlog review, backlog rank, code review, code document, pr draft, pr review, docs create, ticket triage, ticket respond, sec patch	Customize output with editing instructions (provide instructions inline or use edit.md file)
--lite	None (flag only)	issue draft, issue review, issue plan, code review, pr draft, pr review	Focused, reduced output. See Lite Mode Commands.
--lite-edit	Optional instructions	Same as --lite	Lite output with edit instructions (provide instructions inline or use lite-edit.md file)
--fix	Optional instructions	code create, code refactor, pr merge	Apply your fix instructions (provide instructions inline or use fix.md file)

For sec patch, --edit customizes the patch output. For the exact help text per command, see the Command Reference.

Provide modifier instructions

--edit, --lite-edit, and --fix need instructions. Provide them inline or in a file.

Inline

bash

frg issue draft --edit "Emphasize security requirements"
frg issue plan --lite-edit "Prioritize backward compatibility"
frg code create --fix "Focus on error handling in the auth module"
frg pr merge --fix "Resolve the failing lint check"

Use inline instructions for short, one-off guidance.

From a file

If you pass the flag without a value, Forge reads the instructions from the modifier file: edit.md, lite-edit.md, or fix.md.

The file is in the target's folder of the job directory, for example .forge/work/job_42/issue/edit.md for frg issue draft --edit.

bash

export FORGE_ISSUE_ID=42
mkdir -p .forge/work/job_42/issue

cat > .forge/work/job_42/issue/edit.md << 'EOF'
Focus on:
- Performance requirements (< 100 ms response time)
- Input validation
- Backward compatibility with the v1 API
EOF

frg issue draft --edit

Use a file for longer instructions, or to reuse the same instructions across runs.

If you pass neither inline instructions nor a non-empty file, the command stops. See Troubleshooting.

--edit

Refines the operation's output with your instructions. Use it to iterate on a draft, review, plan, or document.

bash

frg issue review --edit "Check the acceptance criteria against the API contract"
frg docs create --edit "Write for first-time contributors"

--lite and --lite-edit

--lite requests a focused, reduced-output variant. It takes no value. --lite-edit is a single combined modifier for lite output with your instructions. Use it instead of --lite --edit, which isn't allowed.

bash

frg issue plan --lite
frg code review --lite-edit "Focus on API security concerns"

See Lite Mode Commands for what each command produces.

--fix

Applies fix instructions that you provide:

Command	Help text
frg code create --fix	Apply fix instructions during generation
frg code refactor --fix	Apply refactoring using your instructions
frg pr merge --fix	Fix merge issues using your instructions

bash

frg code create --fix "Fix the type mismatch errors reported by the build"
frg code refactor --fix "Extract the retry logic into a shared helper"

--auto-fix on code review

frg code review --auto-fix <LEVEL> fixes issues from an existing review, based on severity:

Level	Fixes
critical	Critical issues
major	Critical and major issues
minor	Critical, major, and minor issues
issues	Critical, major, and minor issues
suggestions	Suggestions
all	All issues and suggestions

Run frg code review first. Without an existing review, Forge prints The --auto-fix option requires an existing code review. See Code Operations.

Session and retry options

These options control the agent session. They work on all workflow operations.

Option	Description
--clear	Clear the existing agent session and start fresh. Later commands in the same session group use the new session.
--retry [<INSTRUCTIONS>]	Continue the previous session with a prompt to complete missing outputs. The prompt lists the missing file paths, refers to the original output requirements, and includes your message if you provide one. Requires an existing session.
--auto-retry	Retry the workflow once if output validation fails. Triggers only when expected outputs are missing, runs exactly once, and uses the default missing-outputs prompt.

--retry and --auto-retry can't be used with --clear, because they need the existing session.

bash

# Complete missing outputs with the default prompt
frg code create --retry

# Add your own instructions
frg code create --retry "Add the missing test files"

# Retry once automatically, for example in CI
frg issue plan --auto-retry

Use --clear when the session context is no longer relevant, or after session errors:

bash

frg issue draft --clear

Context and safety options

Option	Description
-c, --context-file <FILE>	Include a file path as context. The agent reads the file as needed. Repeatable.
--context-dir <DIR>	Include a directory as a context source. The agent gets path references and reads files when needed. Repeatable. Paths are relative to the current directory. Max 100 files per directory and 1 MB per file; binary files and hidden directories such as .git and .forge are skipped.
--bypass-safety-checks	Bypass prompt injection safety validation. Bypassed attempts are logged for security audit.

bash

frg code review --context-dir docs/patterns --context-dir examples/

Warning: Use --bypass-safety-checks only when you've verified the input is safe. Common false positives are documentation about prompt injection, security training material, and code examples with shell commands. To reduce false positives, add patterns to the allowlist in .forge/config/.prompt-safety.toml instead. See Prompt Safety.

Custom modifiers

You can define modifiers for your own operations in .forge/config/commands.toml. Each modifier names the task prompt it switches to and, optionally, its input file:

toml

[[commands.operations.modifiers]]
name = "edit"
description = "Customize output with editing instructions"
task_override = "issue_draft_edit"
input_file = "issue_draft_edit"

Give each modifier a descriptive name, create its task prompt variant, and keep the operation working without the modifier. After editing, run frg config validate. See Command Customization.

Troubleshooting

error: unexpected argument '--fixes' found

Cause: The option doesn't exist, or the operation doesn't support it. Forge shows a tip: with a similar option when there is one.

Solution:

1. Check the options for the operation, for example frg code create --help.
2. Use the exact option name, for example --fix, not --fixes.

Multiple modifiers specified: [...]. Only one modifier can be active at a time.

Cause: You passed more than one modifier, for example --lite --edit.

Solution:

1. Keep one modifier.
2. For lite output with instructions, use --lite-edit "<instructions>".

No instructions provided for --edit modifier.

Cause: You passed --edit, --lite-edit, or --fix without a value, and the modifier file doesn't exist.

Solution:

1. Pass the instructions inline, for example frg issue draft --edit "Your instructions here".
2. Or create the modifier file at the path shown in the message, then rerun the command.

Modifier file exists but is empty.

Cause: The modifier file exists but has no content. An empty inline value, such as --edit "", gives a similar Empty instructions provided error.

Solution:

1. Add your instructions to the file, or pass them on the command line.
2. Run the command again.

Run the command without --retry first to establish a session, then use --retry on subsequent attempts if outputs are missing.

Cause: You used --retry but there's no previous session for this command.

Solution:

1. Run the command without --retry.
2. If outputs are missing, run it again with --retry.

See Also

• Lite Mode Commands
• Workflow Commands
• Progress Tracking
• Command Reference
• Command Customization