Configuration Fields Reference

Updated on Oct 5, 2026

This page lists the fields of every Forge configuration file, with their types, allowed values, and defaults. Use it to look up a key; for setup steps, follow the links in each section.

Files and locations

File	Location	Created by	Purpose
project.toml	.forge/config/	frg config init	Project metadata, monorepo, context, commit behavior
toolchain.toml	.forge/config/	frg config init --issues/--tickets/--code/--scanner	Issue tracker, ticket tracker, code platform, security scanner
agents.toml	.forge/config/	frg config init --agent	Default agent, models, commit toggles
commands.toml	.forge/config/	frg config export --commands	Prompt overrides, custom commands, command context
application.toml	.forge/config/ of the application root	frg config init --app	Multi-repository application
telemetry.toml	.forge/config/, ~/.config/forge/, /etc/forge/	You	OTLP export, usage telemetry, OpenSearch
.prompt-safety.toml	.forge/config/	frg config export --security	Prompt-injection detection rules
context.toml	.forge/	frg config set-*, frg config user	Current work item and user identity
workflows/*.toml	.forge/config/workflows/	frg config export --workflows	Stateful workflows; see Workflow Schema Reference

Run frg config validate after you edit a file. For how Forge finds and layers these files, see Context Merging Reference.

project.toml

frg config init writes schema_version = "1.0.0" and a [project] table with language-neutral defaults ("Unknown") that you replace.

Top-level tables

Key	Type	Description
schema_version	string	Schema version. Generated value: "1.0.0".
[project]	table	Project metadata. Required.
[[project.context]]	array of tables	Context sources for every workflow command. See Context source fields.
[monorepo]	table	Monorepo services.
[commit]	table	Commit instructions in prompts.
[config.external_sources]	table	Loading of configuration from the user and system profiles.
[ui]	table	Terminal output preferences.
[routing]	table	Auto-routing classifier used by frg workflow classify and frg workflow run --auto.
[beta_consent]	table	Written by Forge when you accept the beta notice. Do not edit.

[project]

Field	Type	Required	Default written by config init	Description
name	string	Yes	Directory name	Project name. At most 100 characters.
description	string	Yes	"Project description"	Short project summary. At most 250 characters.
language	string	Yes	"Unknown"	Primary language, for example TypeScript, C#, Python. At most 100 characters.
framework	string	Yes	"Unknown"	Framework, or "None". At most 100 characters.
testing_framework	string	Yes	"Unknown"	Test tool, for example jest, xUnit, "go test". At most 100 characters.
package_manager	string	Yes	"Unknown"	Package manager, for example npm, NuGet, "go mod". At most 100 characters.
allow_app	string (UUID)	No	—	Opt this repository into the application with this [application].id. See Multi-Repository Applications.
repository_id	string	No	—	Repository identifier.

You can add custom string fields, such as documentation_framework, for use in prompts. Custom values are limited to 250 characters. See Project Setup.

[routing]

Field	Type	Required	Default	Description
enabled	boolean	No	true	Turns frg workflow classify and frg workflow run --auto on or off.
model	string	No	"claude-haiku-4.5"	Model used for the classification call only. Does not affect the model used by the workflow that ends up running.

See Auto-Routing Issues to Workflows.

[monorepo]

Field	Type	Required	Description
enabled	boolean	Yes	Turn on monorepo mode.
[[monorepo.services]]	array of tables	When enabled = true	Service definitions.

Service fields:

Field	Type	Required	Description
name	string	Yes	Service name used by frg config set-service.
path	string	Yes	Service path relative to the repository root.
description	string	No	Overrides project.description for the service.
language	string	No	Overrides project.language.
framework	string	No	Overrides project.framework.
testing_framework	string	No	Overrides project.testing_framework.
package_manager	string	No	Overrides project.package_manager.

See Monorepo Support.

[commit]

Field	Type	Default	Values
behavior	string	"enabled"	"enabled": include basic commit instructions. "tagged": also add the trailer Co-authored-by: frg <[e-mail]>. "disabled": include no commit instructions.

behavior = "disabled" overrides every commits setting in agents.toml. See Commit Configuration.

[config.external_sources]

Field	Type	Description
enabled	boolean	Master switch for user and system profile configuration. The per-file toggles below have no effect when enabled = false.
agents	boolean	Load agents.toml from external sources.
toolchain	boolean	Load toolchain.toml from external sources.
commands	boolean	Load commands.toml from external sources.
workflows	boolean	Load workflow files from external sources.
telemetry	boolean	Load telemetry.toml from external sources.

A repository that sets allow_app uses the application's [external_sources] instead of this table. FORGE_DISABLE_EXTERNAL_CONFIGS turns off all external sources. See Hierarchical Configuration.

[ui]

Field	Type	Description
show_command_hints	boolean	Show next-step command hints after a command completes. See Command Hints.

toolchain.toml

frg config init writes schema_version = "1.0.0" and one table per tool. At least one of [issue_tracker] or [ticket_tracker] is required.

Table	Configured with	Built-in name values
[issue_tracker]	--issues <TOOL>	github_issues, jira, azure_devops, shortcut, local
[ticket_tracker]	--tickets <TOOL>	github_issues, jira, azure_devops, shortcut, local
[code_platform]	--code <TOOL>	github, github_enterprise, bitbucket, azure_devops, local
[security_scanner]	--scanner <TOOL>	polaris, github_sast

Fields of each tool table:

Field	Type	Required	Values / default	Description
name	string	Yes	See the table above, or your own name	Tool identifier.
type	string	Yes	"built-in", "custom"	Whether Forge ships a definition for the tool.
method	string	Yes	"skill" (written by config init), "cli", "mcp", "api", "local"	How the agent accesses the tool.
description	string	Yes	Multi-line string	Instructions for the agent. Supports placeholders such as {{issue_tracker_repo_slug}} and {{code_platform_skill_name}}.
repository	string	No	owner/repo or Git URL	Repository when it differs from the Git remote.
skill_name	string	No	Default: the tool name	Skill directory for a custom tool with method = "skill".

With method = "api", the agent reads tokens from FORGE_ISSUE_TOKEN, FORGE_TICKET_TOKEN, FORGE_CODE_TOKEN, or FORGE_SECURITY_TOKEN. See Toolchain Configuration.

agents.toml

toml

schema_version = "1.0.0"

[agent]
default = "github_copilot"

[agent.github_copilot]
model = "claude-sonnet-5"

**Validation Rules:**
- Service names must be unique
- Service names must be valid identifiers (alphanumeric, hyphens, underscores)
- Paths must be relative (no leading `/`)
- Paths cannot use `..` parent references
- At least one service required when `enabled = true`

**Related Documentation:** [Monorepo Support Guide](slug://monorepo-configuration-support)

---

## Commit Configuration (project.toml)

Controls how commit instructions are included in AI agent prompts.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `behavior` | string | No | Commit instruction mode: "enabled" (default), "tagged", or "disabled" |

**Example:**
```toml
[commit]
behavior = "enabled"  # Basic commit instructions
# behavior = "tagged"    # Include frg co-author attribution
# behavior = "disabled"  # No commit instructions

Behavior Options:

• "enabled": Include basic commit instructions (default)
• "tagged": Include commit instructions with Co-authored-by: frg <[e-mail]>
• "disabled": Include explicit no-commit instructions (AI should not commit)

Related Documentation: Commit Configuration Guide

---

Branch Configuration (project.toml)

Controls whether and how frg creates/checks out a dedicated git branch before working on a task.

Field	Type	Required	Description
behavior	string	No	Branch creation mode: "auto" (default) or "off"
base	string	No	Ref to fork newly created branches from. Unset = fork from whatever is currently checked out
naming	string	No	Naming template. Default: "frg/issue-{issue}-{slug}". Tokens: {target}, {action}, {slug}, {issue}, {date}
checkout	boolean	No	Whether to check out the branch after creating it (default: true)
on_dirty	string	No	What to do when the working tree is dirty: "carry" (default), "stash", or "error"
on_collision	string	No	What to do when the resolved branch name already exists: "checkout" (default), "suffix", or "error"

Example:

toml

[branch]
behavior = "auto"       # "auto" branches whenever commit instructions would be enabled; "off" never branches
naming = "frg/issue-{issue}-{slug}"
checkout = true
on_dirty = "carry"       # "carry" | "stash" | "error"
on_collision = "checkout" # "checkout" | "suffix" | "error"
# base = "develop"       # omit to fork from whatever is checked out

Behavior Options:

• "auto" (default): Create a branch exactly when the resolved commit instructions for that target/operation would be enabled (reuses the [commit] trigger table). The pr target never auto-branches, since PR operations act on an already-checked-out branch.
• "off": Never create or check out branches automatically, regardless of commit state.

Related Documentation: Branch Configuration Guide

---

Agent Branch Settings (agents.toml)

Control branch-creation behavior per target or operation in agent configuration, mirroring Agent Commit Settings.

Target-Level Settings

Field	Type	Required	Description
branch	string	No	"on" or "off" to enable/disable branch creation for all operations in this target

Example:

toml

[agent.github_copilot.targets]
code = { model = "gpt-4", branch = "on" }
issue = { branch = "off" }

Operation-Level Settings

Field	Type	Required	Description
branch	string	No	"on" or "off" to enable/disable branch creation for this specific operation

Example:

toml

[agent.github_copilot.operations]
"code.review" = { branch = "on" }
"code.create" = { model = "gpt-4", branch = "off" }

Precedence (highest to lowest):

1. project.toml [branch].behavior = "off" (global override)
2. Operation-specific branch setting
3. Target-specific branch setting
4. Built-in default (reuses the resolved [commit] trigger; the pr target is always excluded)

Related Documentation: Branch Configuration Guide

---

Agent Commit Settings (agents.toml)

Control commit behavior per target or operation in agent configuration.

Target-Level Settings

Field	Type	Required	Description
commits	string	No	"on" or "off" to enable/disable commits for all operations in this target

Example:

toml

[agent.github_copilot.targets]
code = { model = "claude-sonnet-5", commits = "on" }

[agent.github_copilot.operations]
"issue.plan" = "claude-opus-5"

Key	Type	Description
schema_version	string	Schema version. Generated value: "1.0.0".
[agent].default	string	Agent used when you omit --agent: claude_code, github_copilot, or opencode.
[agent.<agent>].model	string	Default model for that agent. At most 128 characters.
[agent.<agent>].effort	string	Default reasoning effort passed to a supported agent CLI. Forge does not validate the value.
[agent.<agent>.targets]	table	Per-target settings. Key: a target such as code. Value: a model string or an inline table.
[agent.<agent>.operations]	table	Per-operation settings. Key: "<target>.<operation>", such as "issue.plan". Value: a model string or an inline table.
[agent.<agent>.custom_agents]	table	Custom agent configuration per target.
[agent.<agent>.custom_agent_operations]	table	Custom agent configuration per operation.

Inline table fields for targets and operations:

Field	Type	Values	Description
model	string	Model name	Model for the target or operation.
effort	string	Agent-specific	Reasoning effort. Operation overrides target, which overrides the agent default. See Effort Levels.
commits	string	"on", "off"	Include or omit commit instructions.
custom_agent	string	Custom agent name	Custom agent configuration to use.
prompt_format	string	See Prompt Formats	Prompt format for the agent.

The --model option overrides model settings for one run. See AI Model Selection, Effort Levels, and Custom Agent Configurations.

commands.toml

frg config export --commands writes a commented template. Built-in commands use the same schema.

Key	Type	Description
schema_version	string	Schema version, for example "2.1.0".
[metadata]	table	name, version, author, description.
[[prompt_overrides]]	array of tables	Replace the role or task prompt of a built-in operation.
[[custom_commands]]	array of tables	Define a new target or operation.
[[commands]]	array of tables	Target definitions with context and operations.
[[workflows]]	array of tables	Deprecated alias of [[commands]]. Forge warns: [[workflows]] is deprecated, use [[commands]] instead.

[[prompt_overrides]]

Field	Type	Required	Description
target	string	Yes	Built-in target, for example issue.
operation	string	Yes	Operation, for example draft.
role	string	No	Custom role prompt name.
task	string	No	Custom task prompt name.

[[custom_commands]]

Field	Type	Required	Description
target	string	Yes	Target name, for example deployment.
operation	string	Yes	Operation name, for example plan.
role	string	Yes	Role prompt name.
task	string	Yes	Task prompt name.
description	string	No	Description.

You cannot use a reserved target name: config, guide, shell, status, workflow, app, learn, diagnose. Forge reports Cannot define workflow for reserved target.

[[commands]]

Field	Type	Description
target	string	Target name, for example code.
description	string	Target description.
[[commands.context]]	array of tables	Context sources for all operations of the target.
[[commands.operations]]	array of tables	Operation definitions.

Operation fields:

Field	Type	Description
name	string	Operation name, for example review.
description	string	Operation description.
flags	array of strings	Options the operation accepts, for example ["role", "custom_agent", "edit", "lite", "lite-edit"].
app_workflow	string	Workflow that frg app runs in each child repository. Built-in values: issue plan = issue-to-plan, code create = code-to-review, pr draft and pr publish = pr-create-publish, pr review and pr merge = pr-review-merge.
[commands.operations.prompts]	table	role and task prompt names.
[[commands.operations.modifiers]]	array of tables	Modifier definitions: name, description, task_override, input_file.
[[commands.operations.context]]	array of tables	Context sources for this operation.
pre_steps, pre_checks, post_steps, post_checks	arrays	Steps and checks around the operation. See Command Hooks.

See Command Customization and Context Configuration.

Context source fields

Used by [[project.context]], [[commands.context]], and [[commands.operations.context]].

Field	Type	Required	Values	Description
type	string	Yes	"file", "directory"	Single file or recursive directory.
path	string	Yes	Path inside the repository	File or directory.
description	string	No	At most 500 characters	Why the source matters.

application.toml

frg config init --app writes:

toml

schema_version = "1.0.0"
repositories = []

[application]
id = "186ee0e9-5ef4-490a-bcba-2e38cb7dd98a"
name = "my-app"
description = "Multi-repository application: my-app"

[discovery]
enabled = true
max_depth = 5
exclude = ["node_modules", "target", ".git", "vendor", "dist", "build"]

Key	Type	Default	Description
schema_version	string	"1.0.0"	Schema version.
[application].id	string (UUID)	Generated	Value that repositories reference with allow_app.
[application].name	string	Directory name	Application name.
[application].description	string	Generated	Description.
[discovery].enabled	boolean	true	Turn on repository discovery.
[discovery].max_depth	integer	5	Directory depth to search. Must be at least 1.
[discovery].exclude	array of strings	See the example	Directory names to skip. Empty patterns are rejected.
[[repositories]]	array of tables	[]	Repositories saved by frg app discover. Each entry has name and path.
[external_sources]	table	—	Same fields as [config.external_sources]. Child repositories with allow_app inherit it.
[beta_consent]	table	—	Written by Forge. Do not edit.

telemetry.toml

Forge reads the first file it finds: the path in FORGE_TELEMETRY_PATH, .forge/config/telemetry.toml, ~/.config/forge/telemetry.toml (or $XDG_CONFIG_HOME/forge/telemetry.toml), then /etc/forge/telemetry.toml. Telemetry is on by default; opt out with [usage] enabled = false or FORGE_TELEMETRY_DISABLED=1.

Key	Type	Values / limits	Description
[endpoint].url	string	Starts with http://, https://, or grpc://	OTLP endpoint. Forge logs a security warning for http://.
[endpoint].protocol	string	"http", "grpc"	OTLP transport.
[endpoint].timeout_secs	integer	1–60	Export timeout.
[endpoint.headers]	table	String values	HTTP headers, for example Authorization.
[collect].transactions	boolean		Export transaction events.
[collect].traces	boolean		Export traces.
[collect].logs	boolean		Export logs.
[privacy].strict_privacy	boolean		Hash personal data such as approver email addresses.
[usage].enabled	boolean		Usage telemetry switch.
[consent]	table		Written by Forge (notice_shown, consented, opted_out, and related dates). Do not edit.
[opensearch].uri	string		OpenSearch endpoint.
[opensearch].api_token	string		API token. Never commit it.
[opensearch].accept_invalid_certs	boolean		Accept self-signed certificates.
[opensearch].enforce	boolean		Stop Forge when OpenSearch is not configured.

See OpenSearch Integration and Security Guide.

.prompt-safety.toml

frg config export --security writes the built-in rules to .forge/config/.prompt-safety.toml.

Key	Type	Default	Description
schema_version	string	"1.0.0"	Schema version.
[settings].enabled	boolean	true	Master switch for validation.
[settings].default_severity	string	"error"	Severity for rules without one: "error" blocks execution, "warn" logs a warning.
[[rules]].id	string		Unique rule ID.
[[rules]].name	string		Display name.
[[rules]].description	string		What the rule detects.
[[rules]].pattern	string		Regular expression.
[[rules]].severity	string		"error" or "warn".
[[rules]].tags	array of strings		Categories, for example ["injection", "override"].
[allowlist].strings	array of strings	[]	Exact strings that are always allowed.
[allowlist].regexes	array of strings	Markdown code blocks	Patterns whose matches skip detection.
[allowlist].paths	array of strings	.forge/prompts/examples/, test/fixtures/	Paths excluded from validation.

Built-in rules:

Severity	Rule IDs
error	invisible-unicode, ignore-instructions, forget-instructions, new-role, system-tag, delimiter-injection, jailbreak-attempt, role-override, curl-pipe-bash
warn	rm-recursive, format-drive, drop-table, delete-sql-no-where, git-force-push, chmod-777, base64-payload

Skip validation for one run with --bypass-safety-checks. See Prompt Safety Validation.

context.toml

Forge writes .forge/context.toml when you run frg config set-* or frg config user. Environment variables override the file.

Field	Type	Set with	Environment variable	Description
issue_id	string or integer	frg config set-issue	FORGE_ISSUE_ID	Current issue, for example 123, "PROJ-456", "AB#789".
pr_id	integer or string	frg config set-pr	FORGE_PR_ID	Current pull request number.
ticket_id	string or integer	frg config set-ticket	FORGE_TICKET_ID	Current ticket, for example 123456, "INC0012345".
service_name	string	frg config set-service	—	Selected monorepo service.
user_name	string	frg config user --name	FORGE_USER_NAME	Display name for OpenSearch reporting. At most 256 characters.
user_email	string	frg config user --email	FORGE_USER_EMAIL	Email for OpenSearch reporting. At most 256 characters.
agent_sessions	table	Forge (legacy)	—	Older releases stored agent sessions here. Forge migrates them to .forge/work/job_<id>/sessions.toml and removes the key. Do not add it.

toml

# Forge workflow context
issue_id = "PROJ-456"
pr_id = 128
service_name = "api"
user_email = "[e-mail]"

frg config clear-context removes issue_id and pr_id; user_name and user_email persist. See Context Configuration and Session Context.

Workflow files

Stateful workflow definitions in .forge/config/workflows/*.toml are documented in Workflow Schema Reference and Workflow Steps Reference.

See Also

• Configuration Overview
• Configuration Files Reference
• Environment Variables
• Command Reference