Context Merging Reference

Updated on Oct 2, 2026

This page describes how Forge finds configuration files, which source wins when several exist, and how context sources are combined into a prompt. Use it to predict what a command sees.

Configuration discovery

Forge locates configuration in two passes.

Project root. Forge uses the directory that contains .git/. If none is found, it uses the directory that contains .forge/, and otherwise the current working directory. frg status prints the method, for example Detected via: .git/ directory.
Project files. Forge reads project.toml, toolchain.toml, agents.toml, and commands.toml from <root>/.forge/config/.
Application. Forge searches for application.toml in this order and stops at the first match: the directory tree, the user profile, then the system profile.

Root discovery starts from the command's working directory and searches its parent directories for the project markers. For a workflow run, Forge resolves .forge/context.toml, agent configuration, and the agent working directory from that project root. Starting Forge in a subdirectory therefore uses the enclosing project's context; with frg app, each child repository uses its own project root.

Configuration precedence

frg config show --verbose lists the active sources under Configuration Sources. A higher row overrides a lower row.

Priority	Source	Location	Loaded when
1 (highest)	Repository	`.forge/config/`	Always
2	Application	`.forge/config/application.toml` of the application root	The repository sets `allow_app`, or you run `frg app`
3	User profile	`~/.config/forge/`	External sources are enabled
4	System profile	`/etc/forge/`	External sources are enabled
5 (lowest)	Built-in defaults	Forge binary	Always

External sources

User and system profile files are ignored unless external sources are enabled.

Setting	Effect
`[config.external_sources] enabled = true` in `project.toml`	Enables external sources for a standalone repository.
`agents`, `toolchain`, `commands`, `workflows`, `telemetry` toggles	Limit external loading per file. They have no effect when `enabled = false`.
`[external_sources]` in `application.toml`	Applies to `frg app` commands and to every child repository that sets `allow_app`. Child repositories inherit this setting instead of their own.
`FORGE_DISABLE_EXTERNAL_CONFIGS`	Disables all external sources, regardless of configuration. Use it in CI.

Other values

Value	Precedence (highest first)
Issue ID, PR ID, Ticket ID	`FORGE_ISSUE_ID` / `FORGE_PR_ID` / `FORGE_TICKET_ID`, then `.forge/context.toml`
User identity	`FORGE_USER_NAME` / `FORGE_USER_EMAIL`, then `.forge/context.toml`, then Git `user.name` / `user.email`, then the OS user, then a descriptive fallback
Model	`--model`, then operation, target, and agent defaults in `agents.toml`
`telemetry.toml`	`FORGE_TELEMETRY_PATH`, `.forge/config/`, `~/.config/forge/` (`$XDG_CONFIG_HOME`), `/etc/forge/`
Commit instructions	`[commit] behavior = "disabled"` in `project.toml` overrides every `commits` toggle in `agents.toml`

Context source merging

Context sources tell the agent which files to read. They accumulate rather than override.

Scope	Configured in	Prompt section
Project	`[[project.context]]` in `project.toml`	Project configuration
Target	`[[commands.context]]` in `commands.toml`	Context
Operation	`[[commands.operations.context]]` in `commands.toml`	Context
Job	`.forge/work/job_<id>/context/`, when the directory exists	Context
Command line	`-c/--context-file` and `--context-dir`	Context

Rules:

Union. Forge includes every source from every scope that applies to the command.
Deduplication within the context section. A file that appears in several target, operation, job, or command-line sources is included once.
No deduplication across sections. A file in [[project.context]] and in [[commands.context]] appears in both sections.
Directory expansion. Each eligible file of a directory source becomes its own entry, and its description gets the suffix (from directory).
Limits. A directory source contributes at most 100 files. Files over 1 MB, binary files, and hidden directories such as .git and .forge are skipped. When a directory reaches the limit, Forge logs Maximum file limit reached for directory.
Path safety. Forge resolves each path and rejects paths that resolve outside the repository boundary.

Errors

Message	Cause
`Context file not found: <path>`	A `file` source or `--context-file` path does not exist.
`Context directory not found: <path>`	A `directory` source or `--context-dir` path does not exist.
`Path is not a directory: <path>`	`--context-dir` points to a file. Use `--context-file`.
`... resolves outside repository boundary. Resolved path: <path>`	The path, a `..` segment, or a symlink leaves the repository.

Transaction logs record each context source with its origin, path, source_type, and size. See Transaction Logs Reference.

Worked example

Configuration:

toml

# .forge/config/project.toml
[[project.context]]
type = "file"
path = "docs/architecture.md"

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

[[commands.context]]
type = "directory"
path = "docs/patterns"

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

[[commands.operations.context]]
type = "file"
path = "docs/patterns/errors.md"

Command:

bash

frg code review --context-file docs/architecture.md --print-prompt

Result, assuming docs/patterns/ contains errors.md and retries.md:

Prompt section	Files	Why
Project configuration	`docs/architecture.md`	Project scope
Context	`docs/patterns/errors.md`, `docs/patterns/retries.md`, `docs/architecture.md`	Target directory expanded; the operation entry for `errors.md` is a duplicate; the command-line file is not deduplicated against the project section

Use --print-prompt to check the result before you run the agent.