Skip to main content
The forge.yaml file is the main configuration file for customizing Forge’s behavior in your project.

​
Configuration Schema

Forge uses a JSON schema for validation. You can enable schema validation in your editor: 
# yaml-language-server: $schema=./forge.schema.json

model: claude-3.7-sonnet
temperature: 0.7

​
Core Configuration

​
model

​
model
string
The AI model to use for all agents. Must match a model available from your configured provider.Example:
model: claude-3.7-sonnet
Use /model command in Forge CLI to see available models.

​
custom_rules

​
custom_rules
string
Custom guidelines that all agents should follow when generating responses. Applied in addition to each agent’s individual rules.Example:
custom_rules: |
  1. Always add comprehensive error handling to code
  2. Include unit tests for all new functions
  3. Follow team naming convention: camelCase for variables

​
commands

​
commands
array
Define custom commands as shortcuts for repetitive prompts.Schema:
  • name (string, required) - Command name
  • description (string, required) - Command description
  • prompt (string, optional) - Prompt text to execute
Example:
commands:
  - name: refactor
    description: Refactor selected code
    prompt: "Improve readability and performance of this code"
  - name: review
    description: Review code for issues
    prompt: "Review for bugs, security issues, and best practices"

​
templates

​
templates
string
Path pattern for custom template files (supports glob patterns).Example:
templates: .forge/templates/**/*.md

​
Model Parameters

​
temperature

​
temperature
number
default:"model default"
Controls randomness in the model’s output.
  • Range: 0.0 to 2.0
  • Lower values (0.0-0.3): More focused, deterministic, coherent
  • Higher values (0.7-2.0): More creative, diverse, exploratory
Example:
temperature: 0.7  # Balanced creativity and focus

​
top_p

​
top_p
number
default:"model default"
Controls diversity via nucleus sampling.
  • Range: 0.0 to 1.0
  • Lower values (0.1): More focused on probable tokens
  • Higher values (0.9): More diverse token selection
Example:
top_p: 0.8  # Balanced diversity

​
top_k

​
top_k
integer
default:"model default"
Controls the number of highest probability tokens to keep.
  • Range: 1 to 1000
  • Lower values (10): More focused responses
  • Higher values (100): More diverse responses
Example:
top_k: 30

​
max_tokens

​
max_tokens
integer
default:"model default"
Maximum number of tokens the model can generate.
  • Range: 1 to 100,000
  • Lower values (100): Concise outputs
  • Higher values (20480): Detailed responses
Example:
max_tokens: 20480  # Allow detailed responses

​
Request Limits

​
max_requests_per_turn

​
max_requests_per_turn
integer
default:"50"
Maximum number of requests an agent can make in a single conversation turn.Prevents runaway conversations and controls API usage. When reached, Forge prompts to continue or stop.Example:
max_requests_per_turn: 100

​
max_tool_failure_per_turn

​
max_tool_failure_per_turn
integer
default:"3"
Maximum times a tool can fail before forcing completion.Prevents infinite retry loops when operations repeatedly fail.Example:
max_tool_failure_per_turn: 5  # Allow more retries

​
Project Settings

​
max_walker_depth

​
max_walker_depth
integer
default:"3"
Controls how deeply Forge traverses your project directory structure.
  • Lower values (1): Only immediate subdirectories
  • Higher values (5+): Deep traversal (may be slower)
Example:
max_walker_depth: 3  # Balance context and performance

​
tool_supported

​
tool_supported
boolean
default:"true"
Enable/disable tool support for all agents.Example:
tool_supported: true

​
Context Compaction

​
compact
object
Configuration for automatic context compaction to manage conversation length.Example:
compact:
  token_threshold: 100000
  max_tokens: 2000
  retention_window: 6
  message_threshold: 200
  eviction_window: 0.2
  on_turn_end: false

​
Update Configuration

​
updates
object
Configuration for Forge update checks.Example:
updates:
  frequency: daily
  auto_update: false

​
Complete Example

# yaml-language-server: $schema=./forge.schema.json

# Core settings
model: anthropic/claude-sonnet-4
temperature: 0.7
top_p: 0.8
top_k: 30
max_tokens: 20480

# Request limits
max_requests_per_turn: 100
max_tool_failure_per_turn: 3

# Project settings
max_walker_depth: 3
tool_supported: true

# Custom rules
custom_rules: |
  1. Add error handling to all code
  2. Include unit tests for new functions
  3. Use camelCase for variables, PascalCase for classes

# Custom commands
commands:
  - name: refactor
    description: Refactor code for readability
    prompt: "Refactor this code to improve readability and performance"

# Context compaction
compact:
  token_threshold: 100000
  max_tokens: 2000
  retention_window: 6
  message_threshold: 200
  eviction_window: 0.2
  on_turn_end: false

# Update settings
updates:
  frequency: daily
  auto_update: false

​
Advanced Usage

​
Variables

Use YAML anchors to reuse configuration values: 
variables:
  operating_agent: Forge
  advanced_model: &advanced_model anthropic/claude-sonnet-4

model: *advanced_model

compact:
  model: claude-3-haiku  # Use cheaper model for compaction

​
Schema Validation

Enable schema validation in your editor:
  1. Ensure forge.schema.json is in your project root
  2. Add schema reference to the top of your forge.yaml: 
    # yaml-language-server: $schema=./forge.schema.json

​
Next Steps

Custom Rules

Define project-specific coding guidelines

Environment Variables

Configure runtime behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us