Configuration Files Reference
Quick reference for Forge configuration files: where each file lives, whether it supports hierarchical loading, and its main keys. For every field, see the Configuration Fields Reference.
File overview
| File | Location | Hierarchical | Description |
|---|---|---|---|
project.toml | .forge/config/ | No | Project metadata (required) |
agents.toml | .forge/config/ | Yes | AI agent and model selection |
toolchain.toml | .forge/config/ | Yes | Development tools |
commands.toml | .forge/config/ | Yes | Prompt overrides and custom commands |
workflows/*.toml | .forge/config/workflows/ | Yes | Stateful workflow definitions |
application.toml | <app-root>/.forge/config/ | — | Multi-repository application |
.prompt-safety.toml | .forge/config/ | No | Prompt-injection detection rules |
telemetry.toml | .forge/config/, ~/.config/forge/, /etc/forge/ | Own lookup | Telemetry settings. Override the path with FORGE_TELEMETRY_PATH. |
context.toml | .forge/ | No | Current issue, PR, ticket, service, and user identity |
project.toml
Location: .forge/config/project.toml
| Key | Required | Description |
|---|---|---|
schema_version | Yes | Must be "1.0.0" |
project.name | Yes | Project name (up to 100 characters) |
project.description | Yes | Short description (up to 250 characters) |
project.language | Yes | Primary language |
project.framework | Yes | Framework, or "None" |
project.testing_framework | Yes | Test framework or command |
project.package_manager | Yes | Package manager, or "None" |
project.allow_app | No | Application UUID that this repository joins |
[[project.context]] | No | Context files and directories |
[monorepo] | No | enabled and [[monorepo.services]] |
[commit] | No | behavior = enabled, tagged, or disabled |
[config.external_sources] | No | enabled, agents, toolchain, commands, workflows |
[ui] | No | show_command_hints |
Other keys under [project], such as documentation_framework, are custom fields.
Related: Project Setup
agents.toml
Location: .forge/config/agents.toml
| Key | Description |
|---|---|
agent.default | Default agent: claude_code, github_copilot, or opencode |
agent.<agent>.model | Default model for that agent |
agent.<agent>.effort | Default reasoning effort, when supported by the agent CLI |
agent.<agent>.operations | Per-operation model, effort, or commits overrides, keyed as "<target>.<operation>" |
agent.<agent>.targets | Per-target model, effort, or commits overrides |
Related: Agent Setup, Model Selection, Effort Levels, Commit Behavior Configuration
toolchain.toml
Location: .forge/config/toolchain.toml
| Table | Keys | Description |
|---|---|---|
[issue_tracker] | name, type, method, description, repository, skill_name | Development issue tracker |
[ticket_tracker] | Same as above | Support ticket tracker |
[code_platform] | Same as above | Code hosting platform |
[security_scanner] | Same as above | Security scanner |
Related: Toolchain Configuration
commands.toml
Location: .forge/config/commands.toml
The template created by frg config export --commands uses these tables:
| Table | Description |
|---|---|
[[prompt_overrides]] | Replace the role or task prompt for a built-in target and operation |
[[custom_commands]] | Define a new target and operation with role, task, and description |
The full schema also supports [[commands]] targets with [[commands.context]] and [[commands.operations]] entries.
Related: Workflow Schema, Context Configuration
Create and check configuration
# Project, toolchain, and agent configuration
frg config init --issues github_issues --code github --agent github_copilot
# Application configuration
frg config init --app
# Customization templates
frg config export --commands
frg config export --workflows
frg config export --security
# Validate and lock
frg config validate
frg config lock