forge.yaml Reference

Complete reference for forge.yaml configuration options

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.

Show Compact Configuration Options

compact.token_threshold · integer

Maximum tokens before triggering compaction.

Example: 100000

compact.message_threshold · integer

Maximum messages before triggering compaction.

Example: 200

compact.turn_threshold · integer

Maximum conversation turns before triggering compaction.

Example: 50

compact.max_tokens · integer

Maximum tokens to keep after compaction.

Example: 2000

compact.retention_window · integer · default: "0"

Number of most recent messages to preserve during compaction.

Example: 6

compact.eviction_window · number · default: "0.0"

Maximum percentage of context that can be summarized (0.0 to 1.0).

Example: 0.2 (20% can be compacted)

compact.on_turn_end · boolean

Trigger compaction when the last message is from a user.

Example: false

compact.model · string

Model to use for compaction (useful for cheaper/faster models).

Example: claude-3-haiku

compact.summary_tag · string

Optional tag name to extract content from when summarizing.

Example: summary

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.

Show Update Options

updates.auto_update · boolean · default: "false"

Enable automatic updates.

Example: true

updates.frequency · string · default: "daily"

Update check frequency: daily, weekly, or always.

Example: weekly

Example:

updates:
  frequency: daily
  auto_update: false

Complete Example

Balanced Configuration

# 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