Configuration Overview

Updated on Oct 1, 2026

Forge reads TOML configuration files that describe your project, the AI coding agent to use, your development tools, and any workflow customizations. This page lists the files, shows how to create and inspect them, and explains where Forge looks for them.

Configuration files

Forge stores repository configuration in .forge/config/:

File	Purpose	Created by
project.toml	Project metadata, context sources, commit behavior, external-source settings	frg config init
agents.toml	Default AI agent, model profile, and per-target or per-operation overrides	frg config init --agent <AGENT>
toolchain.toml	Issue tracker, ticket tracker, code platform, and security scanner	frg config init --issues <TOOL> --code <TOOL>
commands.toml	Prompt overrides and custom commands	frg config export --commands
workflows/*.toml	Stateful workflow definitions	frg config export --workflows
.prompt-safety.toml	Prompt-injection detection rules	frg config export --security
application.toml	Multi-repository application settings	frg config init --app
telemetry.toml	Telemetry endpoint and privacy settings	Created manually

Forge also keeps per-developer workflow context (issue ID, PR ID, ticket ID, service, user identity) in .forge/context.toml. The frg config set-*, clear-*, and user commands manage that file. See Context Configuration.

Get started

1. Initialize the project, optionally with a toolchain and an agent:

   bash

   frg config init --issues github_issues --code github --agent github_copilot

2. Edit .forge/config/project.toml to describe your project. See Project Setup.

3. Validate the configuration:

   bash

   frg config validate

4. Optionally lock the configuration to detect drift:

   bash

   frg config lock

Inspect your configuration

Run frg config show to display the current configuration state. This command is read-only.

bash

frg config show

Option	Description
-v, --verbose	Show additional details, including file paths
--no-color	Disable colored output. Output is also plain when piped or when NO_COLOR=1 is set.
-q, --quiet	Suppress all output except errors

The output contains these sections:

Section	Contents
Project Configuration	Name, description, language, framework, test framework, package manager, application status, monorepo status
Agent Configuration	Default agent and model profile, default model, command overrides
Toolchain Configuration	Issue tracker, code platform, ticket tracker, and security scanner, each with its access method
Workflow Context	Issue ID, PR ID, ticket ID, service, and user
Configuration Status	Lock status and counts of custom prompts, skills, workflows, and commands
Configuration Sources	Files loaded from the repository, application, user profile, and system profile
Configuration Files	Path and existence of each configuration file (with --verbose)

To check files for errors, run frg config validate. It reports each file as valid, invalid, or absent, with the source it was loaded from (Repo, App, or User), then checks agent dependencies and workflows.

Configuration hierarchy

Forge can load agents.toml, toolchain.toml, commands.toml, and workflows from several locations. Higher-priority sources override lower-priority ones:

1. Repository: .forge/config/
2. Application: the application.toml directory of a multi-repository application
3. User profile: ~/.config/forge/ (or $XDG_CONFIG_HOME/forge/)
4. System profile: /etc/forge/

By default, Forge loads only repository configuration. You must enable user and system sources in project.toml. See Hierarchical Configuration.

See Also

• Configuration Files
• Project Setup
• Context Configuration
• Commit Behavior Configuration
• Toolchain Configuration
• Hierarchical Configuration
• Agent Skills
• Version Control Setup