Progress Tracking

Updated on Oct 5, 2026

Forge shows the progress of each workflow command in the terminal: which inputs it checked, what the agent is doing, and which expected outputs were created. This page explains that display and how to stream the agent's live trace with --tail.

What a workflow run shows

A workflow run prints these sections in order:

Context: The current Issue ID, PR ID, Service, and Ticket ID, or (not set).
Workspace: Workspace validated: <job directory>.
Required Inputs: The files the operation needs, marked as present, (missing), or (empty).
Agent status: A spinner with Executing AI agent (<agent>) | Runtime: <time>.
Expected Outputs: The files the agent should create or modify.
Completion summary: Output counts, the output directory, and next command hints.

Example output (abbreviated):

text

Issue ID: 42
PR ID: (not set)

Workspace validated: .forge/work/job_42/

Required Inputs:
 ✓ .forge/work/job_42/issue/issue.md

Executing AI agent (github_copilot) | Runtime: 00:01:23

Expected Outputs:
 ✓ README.md
 ○ tasks.md

4 of 5 expected outputs created
Outputs written to: .forge/work/job_42/code/

Use -q or --quiet to suppress all output except errors.

Input validation

Before Forge starts the agent, it checks that the operation's required input files exist. The requirements come from the <context> section of the operation's task prompt.

If a required file is missing, the command stops before the agent runs:

text

Required input files missing: <files>
Hint: Run 'frg issue plan' to generate implementation plan

The hint depends on the missing file. For example, a missing issue file suggests Hint: Run 'frg issue draft' to create the issue file.

Fallback instructions

Some task prompts define a <fallback> for a missing input, such as retrieving a ticket from the ticket tracker. In that case Forge continues:

text

Some required files are missing, but fallback is available:
Workflow will attempt to proceed using fallback...

Lite inputs

Forge adjusts validation for lite outputs:

After frg issue plan --lite, code commands skip input file validation for the single-phase plan.
After frg pr review --lite, frg pr merge validates only pr_review.md.

See Lite Mode Commands.

Output tracking

Forge reads the expected outputs from the <output_requirements> section of the task prompt. It lists them under Expected Outputs and checks them when the agent finishes.

Note: File status is resolved when the workflow finalizes, not while the agent writes files.

Icon	Meaning
○	File not yet created or modified
●	File created or modified; workflow still running
✓	Workflow complete; file exists
⚠	Workflow complete; file not created

File name patterns

An output requirement can name one file, such as README.md, or a pattern for several files, such as phase_{n}.md. Forge converts these pattern tokens to wildcards:

Token	Converted to	Example
`_x`, `_n`, `_X`, `_N`	`_*`	`step_x.md` matches `step_a.md`
`{x}`, `{n}`, `{id}`, `{num}`	`*`	`phase_{n}.md` matches `phase_1.md`, `phase_2.md`

A pattern requirement is complete when at least one matching file exists and isn't empty. If no file matches, the requirement is reported as missing.

A file that didn't exist when the run started must exist and be non-empty. A file that already existed must have changed content.

Completion summary

When the agent finishes, Forge prints one of these:

text

All 5 expected outputs created
Outputs written to: .forge/work/job_42/code/

text

4 of 5 expected outputs created
Outputs written to: .forge/work/job_42/code/

AI agents are non-deterministic and don't always create every expected file. Missing outputs are reported as warnings, not errors.

To complete missing outputs in the same agent session:

bash

# Ask the agent to create the missing files
frg issue plan --retry

# Add your own instructions
frg issue plan --retry "Create tasks.md from the phases you already wrote"

# Retry once automatically on the next run
frg issue plan --auto-retry

--retry and --auto-retry can't be combined with --clear. See Modifiers.

Stream the agent trace with --tail

Forge writes the agent's execution trace to the job's traces/ directory, for example .forge/work/job_42/traces/. Use the global --tail option to stream it, similar to tail -f.

Note: Forge has no frg trace command. Use frg --tail, or open the trace files in the job's traces/ directory.

Run the workflow in one terminal and tail it in another:

bash

# Terminal 1
export FORGE_ISSUE_ID=42
frg issue plan

# Terminal 2
FORGE_ISSUE_ID=42 frg --tail

frg ask and frg run also accept --tail to follow agent execution output in real time:

bash

frg ask --tail "How does the caching layer work?"
frg run --tail "Add input validation to the login form"

Tail options

Command	Behavior
`frg --tail`	Streams the current trace file. Requires an active job context (`FORGE_ISSUE_ID`). Exits after 5 minutes of inactivity.
`frg --tail --continue`	Keeps monitoring across multiple `frg` commands. Never exits due to inactivity; press Ctrl+C to stop.

With --continue, Forge:

Switches to newer trace files in the active job's traces/ directory.
Also monitors standalone frg ask and frg run commands, which write to a fixed, context-independent directory, and switches to their trace file when it becomes the most recent one.
Adapts when you change context (FORGE_ISSUE_ID or FORGE_TICKET_ID).
Checks for content updates every 500 ms, and discovers new trace files every 10 seconds, only when idle.

bash

FORGE_ISSUE_ID=42 frg --tail --continue

Forge prints Continuous tail mode active. Press Ctrl+C to stop. when continuous mode starts.

If no trace appears, Forge prints Waiting for trace file and eventually Timeout waiting for trace file (...). If the job has no trace directory, it prints Trace directory not found: <path>. For fixes, see Tail Issues.

Limitations

Concurrent workflows

Progress tracking is designed for one workflow at a time per repository. Running several Forge workflows in the same working tree can report inaccurate file status.

To work on several issues in parallel, use a separate Git worktree for each:

bash

git worktree add ../frg-issue-43 main
cd ../frg-issue-43
frg config set-issue 43
frg issue plan

Troubleshooting

No "Expected Outputs" section

Cause: The operation's task prompt has no <output_requirements> section, or it couldn't be parsed.

Solution:

No action is needed; the workflow still completes.
For a custom prompt, add an <output_requirements> section to track outputs.

Required input files missing:

Cause: A previous step in the SDLC flow hasn't run for this job.

Solution:

Run the command suggested in the Hint: line, for example frg issue draft or frg issue plan.
Check the current job with frg config show-context.
Rerun the original command.

An output file exists but is reported as missing

Cause: The file is empty, is outside the job directory, or its name doesn't match the expected name or pattern.

Solution:

Check that the file is in the job's output directory shown by Outputs written to:.
Check that the name matches the expected output exactly.
Check that the file isn't empty and that Forge can read it.
Run the command again with --retry to let the agent complete it.