Session Context and Token Optimization

Updated on Oct 1, 2026

Forge reuses AI agent sessions across related workflow commands, so the agent keeps what it has already learned about your task and Forge sends shorter prompts. This page explains how session reuse and delta prompts work, where Forge stores session data, and how to reset or retry a session.

How session reuse works

Every workflow command belongs to a session group. When you run a command, Forge looks up the stored session for that group and the selected agent. If a session exists, Forge resumes it. Otherwise, Forge starts a new session and records it.

bash

frg issue draft
frg issue review # Resumes the issue session
frg issue ask "Which acceptance criteria are still vague?"

Group key	Commands
`ask`	`ask`
`run`	`run`
`backlog`	`backlog create`, `review`, `rank`, `ask`
`issue`	`issue draft`, `publish`, `review`, `triage`, `split`, `ask`
`issue_plan`	`issue plan`
`code`	`code create`, `refactor`, `document`, `build`, `test`, `ask`
`code_review`	`code review`
`docs`	`docs create`, `build`, `ask`
`pr`	`pr draft`, `publish`, `merge`, `ask`
`pr_review`	`pr review`
`sec`	`sec audit`, `patch`, `ask`
`ticket`	`ticket triage`, `respond`, `ask`, `correlate`

issue plan, code review, and pr review have their own groups. They use a different role than the other commands of their target, so they don't inherit the drafting conversation.

Sessions are tracked per agent. If you run frg code create with one agent and then frg code test --agent opencode, Forge starts a separate OpenCode session.

Note: claude_code sessions are shared across the commands of a session group, and an unknown agent ID starts a fresh session instead of reusing another agent's session.

Delta prompts

The first time you run a command in a session, Forge sends the full init prompt: role, project configuration, and task instructions. When you run the same command again in that session, Forge sends a shorter delta prompt with the task instructions only.

Forge tracks this per command, not per session group:

Scenario	Prompt sent
First run of a command	Init: role + project configuration + task
Repeated run of the same command	Delta: task only
First run of a different command in the same group	Init

If Forge can't read the command execution history, it uses the init prompt.

bash

frg code create # Init prompt
frg code test # Init prompt (first run of code test)
frg code create # Delta prompt

Delta prompt files use a _delta suffix, for example issue_draft_delta.task.md. To see both variants, export the prompts with frg config export --prompts --target issue. See Command Customization.

Session storage

Forge stores session data per job in .forge/work/job_<id>/sessions.toml, with a separate namespace for each agent. Don't edit this file by hand; use --clear instead.

If .forge/context.toml contains legacy [agent_sessions] data, Forge migrates it to the job directory automatically.

frg config clear-context doesn't delete sessions. It clears the Issue ID, PR ID, Ticket ID, and service from .forge/context.toml and reports:

✓ Cleared workflow context (Issue ID, PR ID, Ticket ID, and service)
ℹ Context saved to .forge/context.toml
ℹ Agent sessions are preserved in job directories (.forge/work/job_*/sessions.toml)

Reset or retry a session

These flags are available on workflow commands. Check frg <command> <operation> --help for the exact set.

Option	Description
`--clear`	Clear the existing agent session and start fresh. Later commands in the same 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, references the original output requirements, and adds your instructions if you provide them. Requires an existing session.
`--auto-retry`	Retry once automatically if output validation fails because expected outputs are missing. Uses the default missing-outputs prompt.

You can't combine --retry or --auto-retry with --clear.

bash

# Start the plan over with a fresh session
frg issue plan --clear

# Ask the agent to finish missing outputs
frg code create --retry "Also add the unit tests listed in tasks.md"

# Retry once automatically if outputs are missing
frg docs create --auto-retry

frg app commands that use workflow execution don't accept --clear. See Multi-Repository Application Commands.

Troubleshooting

The --retry flag requires a previous session to continue.

Cause: Forge has no stored session for this command's group and agent. For example, this is the first run, you switched agents, or you work on a different job.

Solution:

Run the command without --retry to establish a session.
If outputs are still missing, run the command again with --retry.

The agent reports that the session expired or can't be resumed

Cause: The agent no longer has the stored session. Forge recognizes agent errors such as session not found, session expired, invalid session, session does not exist, cannot resume session, session unavailable, no such session, and session has been closed.

Solution:

Run the command again. Forge clears the stale session after this error, so the next run starts fresh.
If the error persists, run the command with --clear.

Multiple sessions exist with name ''

Cause: GitHub Copilot uses named sessions. A duplicate appears when a previous session was cancelled before completion, or when an older session uses the naming format without a repository prefix.

Solution:

Run copilot --resume (a GitHub Copilot CLI command) to open the session picker.
Select one of the duplicate sessions listed in the error.
Press x to delete the selected session. Delete only one duplicate, not all sessions with that name.
Exit Copilot with Ctrl+C.
Run your Forge command again.

Alternatively, run the Forge command with --clear to start a fresh session with the current naming format.