Tail Issues

Updated on Oct 1, 2026

frg --tail streams the agent's trace file while a command runs, like tail -f. This page explains how tail finds the file and fixes the problems you can hit with it.

How tail works

Run the workflow command in one terminal and frg --tail in a second terminal with the same context:

bash

# Terminal 1
export FORGE_ISSUE_ID=42
frg issue draft

# Terminal 2
export FORGE_ISSUE_ID=42
frg --tail

• Job context. Tail needs an Issue ID or Ticket ID to find .forge/work/<job>/traces/. A PR ID alone is not enough.
• Single file. Without --continue, tail follows the newest trace file and exits after 5 minutes without new content.
• Continuous mode. With --continue, tail never exits on inactivity. It switches to newer trace files in the job's traces/ directory, also watches frg ask and frg run traces in .forge/work/ask/traces/ and .forge/work/run/traces/, and adapts when the context changes. Stop it with Ctrl+C.
• Windows. Tail opens trace files without blocking their deletion.

Event	Interval
Content polling	500 ms
Trace file discovery in --continue mode	10 s, only when the current file is idle

Formatted agent output

Claude Code and OpenCode write JSON Lines. Tail converts them to readable text; plain-text agents such as GitHub Copilot CLI are shown unchanged. If a line cannot be parsed, tail prints it as is. Trace files on disk are not modified.

Example output for Claude Code (abbreviated):

text

--- Claude Code (claude-sonnet-5) ---
[assistant] Let me analyze the code.
--- Complete ---

Starting tail

No job context available for tail command

Full message:

text

Error: Validation error: No job context available for tail command

The --tail command requires an active job context (Issue ID or Ticket ID).

Set job context using one of these methods:
1. Environment variable: export FORGE_ISSUE_ID=<number> or export FORGE_TICKET_ID=<id>
2. Config file: frg config set-issue <number>

View current context: frg config show-context

Cause

Neither an Issue ID nor a Ticket ID is set in the terminal where you run frg --tail.

Solution

1. Set the same context as the terminal running the workflow:

bash

export FORGE_ISSUE_ID=42

Or save it for the project:

bash

frg config set-issue 42

2. Start tail:

bash

frg --tail

Verify

bash

frg config show-context

Trace directory not found

text

Trace directory not found: <path>
This usually means the workflow hasn't been executed yet or the job ID is incorrect.

Cause

No workflow has created traces for this job yet, the context ID differs from the one the workflow uses, or you are in a different repository.

Solution

1. Check the context in both terminals:

bash

frg config show-context

2. Check which job directories exist:

bash

ls -la .forge/work/

3. Start the workflow first, then start tail:

bash

frg issue draft

4. Make sure both terminals are in the same repository root.

Timeout waiting for trace file

text

Timeout waiting for trace file (<duration>)
The workflow may not have started or there may be an issue.

Cause

The trace directory exists, but no trace file appeared in time. The workflow is not running, or it failed before the agent started, for example because the agent is not installed or the license is missing.

Solution

1. Check that the workflow is running in the other terminal.
2. Run the workflow command without tail and read its error message:

bash

frg issue draft

3. Check the job log:

bash

grep -i error .forge/work/job_42/logs/system.log

4. Check readiness:

bash

frg status

You don't have permission to read this trace file.

Cause

The trace file belongs to another user, typically because a workflow ran with sudo or under a service account.

Solution

1. Check the owner:

bash

ls -la .forge/work/job_42/traces/

2. Make the file readable for your user:

bash

chmod +r .forge/work/job_42/traces/*.trace.md

3. Run Forge commands as the same user from then on.

While streaming

Output arrives in bursts

Cause

This is expected. Tail polls for new content every 500 ms, and many agents buffer output before they write it. For a large existing file you see Warning: Large trace file (<n> MB). Streaming may take a moment.... Network file systems add delay.

Solution

1. Wait. A delay under a second between agent output and display is normal.
2. If nothing appears for minutes, check that the file is still growing:

bash

ls -l .forge/work/job_42/traces/

3. Keep .forge/work/ on a local disk rather than a network share.

Warning: Trace file appears to have been rotated or truncated.

Cause

The trace file became smaller than the position tail had read to, for example because a new run reused the file.

Solution

No action needed. Tail restarts from the beginning of the file (Restarting from beginning of file...).

Trace file disappeared (moved or deleted)

Cause

The trace file was deleted or moved while tail was reading it, for example by cleaning up .forge/work/.

Solution

1. Start tail again, or use frg --tail --continue so it picks up the next trace file automatically.
2. Do not delete job directories while a workflow runs.

Tail keeps running after the agent finishes

Cause

Without --continue, tail waits 5 minutes without new content before it exits, so it can show the agent's final output. With --continue, it never exits on its own.

Solution

Press Ctrl+C to stop tail. The workflow is not affected.

Continuous mode (--continue)

Tail does not switch to the new trace file

Cause

Tail looks for newer trace files every 10 seconds, and only while the current file is idle. While the current file keeps receiving content, it stays on that file.

Solution

Wait until the current file stops changing. Tail switches within the next 10 seconds and prints Switching to newer tracefile: <file>.

Context change is not detected

Cause

A variable you export in another terminal is not visible to the running tail process. Tail can only react to context it can read, such as the project context file.

Solution

1. Change the context with a command that writes the context file:

bash

frg config set-issue 43

2. Or stop tail with Ctrl+C and start it again with the new variable:

bash

FORGE_ISSUE_ID=43 frg --tail --continue

Some trace files were skipped

Cause

This is by design. Continuous mode always follows the most recent trace file. When you run several commands quickly, intermediate files are not streamed.

Solution

Read the skipped files directly:

bash

ls -t .forge/work/job_42/traces/
less .forge/work/job_42/traces/<file>.trace.md

See Also

• Common Issues and Solutions
• Progress Tracking
• Workflow Commands
• Environment Variables