Context Configuration

Updated on Oct 1, 2026

Context tells the AI agent which repository files and directories are relevant to a workflow. It also covers the current issue, pull request, ticket, and service that Forge commands work on. This page shows how to configure both.

Prerequisites

Forge is initialized in the repository. See Project Setup.
The files and directories you reference exist inside the repository.

Context sources

A context source is a file or a directory:

Property	Required	Description
`type`	Yes	`file` adds one file. `directory` adds eligible files under the directory, recursively.
`path`	Yes	Path that resolves inside the repository
`description`	No	Why the source matters, up to 500 characters

Scopes

Scope	Where to configure	Applies to
Project	`[[project.context]]` in `.forge/config/project.toml`	Every workflow command
Target	`[[commands.context]]` in `.forge/config/commands.toml`	All operations of one target, such as `code`
Operation	`[[commands.operations.context]]` in `.forge/config/commands.toml`	One operation, such as `code review`
Job	`.forge/work/job_<id>/context/`	One job, when the directory exists
Command line	`-c`/`--context-file <FILE>` and `--context-dir <DIR>`	One invocation

For how the scopes merge, deduplicate, and appear in the prompt, see Context Merging Reference.

Configure project context

Add one [[project.context]] entry per source in project.toml:

toml

[[project.context]]
type = "file"
path = "docs/architecture.md"
description = "System architecture and design decisions"

[[project.context]]
type = "directory"
path = "docs/adr"
description = "Architecture decision records"

Configure target and operation context

Add context to a command target and its operations in commands.toml:

toml

schema_version = "2.1.0"

[metadata]
name = "Project Commands"
version = "1.0.0"
author = "Development Team"

[[commands]]
target = "code"
description = "Code generation and review"

[[commands.context]]
type = "directory"
path = "docs/code-patterns"
description = "Reusable code patterns"

[[commands.operations]]
name = "review"
description = "Review code changes"

[[commands.operations.context]]
type = "file"
path = "docs/review-checklist.md"
description = "Required code review checks"

Forge also accepts the legacy [[workflows]] and [[workflows.context]] table names. Use [[commands]] for new configuration.

Add context for one command

Workflow commands accept -c/--context-file and --context-dir. Repeat either flag to add several sources:

bash

frg code review --context-file docs/hotfix-notes.md
frg issue draft --context-file requirements.md --context-dir docs/specs

Utility commands such as frg config validate do not accept these flags.

Validate and inspect context

Validate the configuration:
bash
```
frg config validate
```
Validation rejects an unsupported type and a description longer than 500 characters. Forge checks that paths exist and stay inside the repository when a workflow runs.
To see the generated prompt, use the workflow's --print-prompt option:
bash
```
frg code review --print-prompt
```
The output can contain paths and project details. Review it before sharing.

How Forge resolves context

Forge canonicalizes each path and rejects paths that resolve outside the repository, including through .. or symlinks.
Directory sources skip hidden entries, dependency and build directories (such as node_modules and target), binary files, and files over 1 MB. Each directory source collects at most 100 files.
Project context is kept separate from target, operation, job, and command-line context. Within the target-operation group, each file appears once.

See Context Merging Reference for the full rules.

Warning: Context paths tell the agent where to look, but they do not limit what the agent can read. Never reference credentials, .env files, or keys. See Agent File System Access.

Set the current issue, PR, ticket, and service

Workflow commands read the current work item from .forge/context.toml or from environment variables. Environment variables take precedence.

Command	Effect	Environment variable
`frg config set-issue <ISSUE_ID>`	Set the issue ID, such as `123`, `PROJ-456`, or `AB#789`	`FORGE_ISSUE_ID`
`frg config set-pr <PR_ID>`	Set the pull request number	`FORGE_PR_ID`
`frg config set-ticket <TICKET_ID>`	Set the ticket ID, such as `123456` or `INC0012345`	`FORGE_TICKET_ID`
`frg config set-service <SERVICE_NAME>`	Select a monorepo service	—
`frg config show-context`	Show current values and where each value comes from	—
`frg config clear-issue` / `clear-pr` / `clear-ticket` / `clear-service`	Clear one value	—
`frg config clear-context`	Clear the issue ID and PR ID	—
`frg config user --email <EMAIL> [--name <NAME>]`	Set the user identity for OpenSearch reporting	`FORGE_USER_EMAIL`, `FORGE_USER_NAME`

The clear-* commands change only .forge/context.toml. Unset environment variables yourself. The user identity persists across frg config clear-context.

For example:

bash

frg config set-issue 42
frg config show-context

Troubleshooting

Context file not found: `or`Context directory not found:

Cause: The configured path does not exist, or the command runs from a different repository.

Solution:

Check the spelling and case of path.
Use a path relative to the repository root.
Run the command from the intended repository.

resolves outside repository boundary

Cause: The path uses .., an absolute location, or a symlink that resolves outside the repository.

Solution:

Move the file inside the repository.
Update path to a location below the repository root.

unknown variant ..., expected file or directory

Cause: A context entry has an unsupported type.

Solution:

Set type = "file" or type = "directory".
Run frg config validate.

description exceeds 500 character limit

Cause: A context description is longer than 500 characters.

Solution:

Shorten the description.
Run frg config validate.

A directory contributes fewer files than expected

Cause: Forge skips hidden, dependency, build, binary, and oversized files, and stops at 100 files per directory source.

Solution:

Point the source at a narrower directory.
Add important files individually with type = "file" or --context-file.

Context is missing from a command

Cause: The source is configured at a scope that does not apply to the command.

Solution:

Put shared references in [[project.context]].
Put target references in [[commands.context]] and operation references in [[commands.operations.context]].
Inspect the prompt with --print-prompt.

A workflow uses the wrong issue or PR

Cause: An environment variable overrides .forge/context.toml.

Solution:

Run frg config show-context to see the source of each value.
Unset the environment variable, for example unset FORGE_ISSUE_ID.