Using Context Effectively

Updated on Oct 1, 2026

Context points the AI agent at files it should consult, such as architecture documents, API specifications, or review checklists. This page shows common patterns for adding context from the command line and from configuration. For the complete configuration reference, see Context Configuration.

How context works

Forge doesn't paste file contents into the prompt. It lists file and directory paths, with optional descriptions, in an additional_context section of the prompt. The agent reads the files when it needs them.

As a result:

• Large files don't increase the prompt size. Only paths and descriptions do.
• The agent reads the current file content at run time.
• The agent decides what to read, so focused paths and clear descriptions matter.

Add context from the command line

Option	Description
-c, --context-file <FILE>	Include a file path as context. Repeat the flag for multiple files. Relative and absolute paths are supported.
--context-dir <DIR>	Include a directory and its text files as path references. Repeat the flag for multiple directories. Paths are resolved relative to the current working directory.

Limits for --context-dir:

• Maximum 100 files per directory.
• Maximum 1 MB per file.
• Binary files and hidden directories (.git, .forge, and so on) are excluded.

bash

# One file
frg issue draft --context-file docs/requirements.md

# Several files
frg code create -c docs/api.yaml -c docs/models.md

# A directory
frg code review --context-dir docs/patterns

# Files and directories together
frg issue plan --context-file docs/architecture.md --context-dir docs/adr

These flags are available on workflow commands such as issue, code, pr, and docs. frg app commands that use workflow execution don't accept --context-file. See Multi-Repository Application Commands.

Add context from configuration

Use configuration for context that applies every time a command runs:

Scope	Where to define it	Applies to
Project	[[project.context]] in .forge/config/project.toml	Every workflow command
Target	[[commands.context]] in .forge/config/commands.toml	All operations of a target, such as code
Operation	[[commands.operations.context]] in .forge/config/commands.toml	One operation, such as code review
Command line	--context-file, --context-dir	One run

Each entry has a type (file or directory), a path relative to the repository root, and an optional description. Run frg config validate after you edit the configuration.

Patterns

Architecture documents for every command

toml

# .forge/config/project.toml
[[project.context]]
type = "file"
path = "docs/ARCHITECTURE.md"
description = "System architecture and key design decisions"

[[project.context]]
type = "file"
path = "docs/CONVENTIONS.md"
description = "Team coding conventions"

A checklist for code review only

toml

# .forge/config/commands.toml
[[commands]]
target = "code"

[[commands.operations]]
name = "review"

[[commands.operations.context]]
type = "file"
path = "docs/REVIEW_CHECKLIST.md"
description = "Required checks for every code review"

A partial entry like this adds context to the built-in operation and keeps its prompts and other settings.

API specifications for all code commands

toml

# .forge/config/commands.toml
[[commands]]
target = "code"

[[commands.context]]
type = "directory"
path = "api/specs"
description = "OpenAPI specifications for all services"

Temporary context for one task

Combine configured context with command-line flags:

bash

frg code create \
  --context-file docs/features/new-auth-flow.md \
  --context-dir spike/auth-research

One service in a monorepo

Select the service so the agent receives its metadata, and add service-specific documents with a flag:

bash

frg config set-service payments
frg code create --context-dir services/payments/docs

See Monorepo Configuration Support.

Tips

• Keep sources focused. Point at specific files or narrow directories, not a whole docs/ tree.
• Write descriptions that say when to read the file, for example "Security requirements for all authentication code".
• Put stable references in configuration and one-off references in command-line flags.
• Inspect the composed prompt with --print-prompt. It displays the compiled prompt without running the agent. Treat the output as sensitive, because it can expose paths and workflow context.

Troubleshooting

Context file not found: <path> or Context directory not found: <path>

Cause: The path doesn't exist where Forge resolves it. Configured paths are relative to the repository root. --context-dir paths are relative to the current working directory.

Solution:

1. Check the spelling of the path.
2. Run the command from the repository root, or use an absolute path with --context-file.
3. For configured entries, run frg config validate.

Context path <path> resolves outside repository boundary.

Cause: A configured path leaves the repository, for example through .. or a symbolic link.

Solution: Reference a file or directory inside the repository.

A directory contributes fewer files than expected

Cause: Forge skips binary files, hidden directories, and files larger than 1 MB, and collects at most 100 files per directory.

Solution: Split the directory into narrower --context-dir entries, or list the key files with --context-file.

The agent doesn't use the context

Cause: The agent decides which referenced files to read.

Solution:

1. Add a description that explains when the file is relevant.
2. Replace broad directories with the specific files that matter.
3. Run the command with --print-prompt to confirm the context is listed.

See Also

• Context Configuration
• Command Customization
• Monorepo Configuration Support
• Security Guide