Configuration Reference

Forge uses layered configuration. Each layer overrides the one below it.

Precedence (lowest to highest)

1. Built-in defaults (hardcoded in Forge)
2. Global user config: ~/.forge/config.toml
3. Team config: <repo>/.forge/team.yml (shared, checked into the repo)
4. Per-repo user config: <repo>/.forge/config.toml (personal, not checked in)
5. Environment variables (see Environment Variables)
6. CLI flags (highest priority, override everything)

Team config takes precedence over global user config for shared concerns (plugins, health checks, ignored paths, language rules). User config wins for personal concerns (editor integration, color preferences).

---

Global Config: ~/.forge/config.toml

This file stores your personal Forge preferences. It applies to all repositories on this machine.

~/.forge/config.toml

# Logging level: trace, debug, info, warn, error
log_level = "info"

# Override the default Forge data directory (~/.forge)
# data_dir = "/path/to/custom/dir"

# Embedding provider: "ollama" or "ort" (ONNX Runtime)
embedding_provider = "ollama"

# Ollama server URL (default reads from OLLAMA_HOST env var or localhost)
ollama_host = "http://localhost:11434"

# Embedding model name
embedding_model = "nomic-embed-text-v1.5"

# Maximum files per repository before a warning is printed
# (Community Mode hard-limits at 10,000)
max_files_warning = 50000

Global Config Options

Option	Type	Default	Description
log_level	string	"info"	Default log verbosity. Override per-run with --log-level.
data_dir	string	~/.forge	Base directory for all Forge state files (license, stats, heartbeat, indexes).
embedding_provider	string	"ollama"	Embedding backend: "ollama" or "ort".
ollama_host	string	"http://localhost:11434"	Ollama server URL. Also reads OLLAMA_HOST env var.
embedding_model	string	"nomic-embed-text-v1.5"	Model name for embedding generation.
max_files_warning	integer	50000	File count threshold for a warning during indexing.

---

Per-Repo Config: <repo>/.forge/config.toml

Overrides the global config for a specific repository. Typically not checked into version control (add .forge/config.toml to .gitignore). Use this for repository-specific embedding settings or ignored paths that are personal rather than shared.

# <repo>/.forge/config.toml

# Repository-specific ignored paths (in addition to .gitignore)
ignored_paths = [
  "dist/",
  "coverage/",
  ".next/",
]

# Override embedding model for this repo
# embedding_model = "nomic-embed-text-v1.5"

Per-Repo Config Options

Option	Type	Default	Description
ignored_paths	array of strings	[]	Gitignore-style path patterns to exclude from indexing. Appended to any global ignored paths.
embedding_model	string	(inherits global)	Override the embedding model for this repo.
embedding_provider	string	(inherits global)	Override the embedding provider for this repo.

---

Team Config: <repo>/.forge/team.yml

The team config is checked into the repository and applies to every developer on the team. It requires a Team tier license to be loaded and enforced.

When present, Forge loads it alongside the user config. Team config wins for shared concerns; user config wins for personal preferences.

If .forge/team.yml is malformed (YAML error), Forge logs a warning and continues with user-config-only mode. A broken team config never blocks indexing.

# <repo>/.forge/team.yml — checked into the repo; applies to everyone on the team.

plugins:
  - react-best-practices
  - rust-cargo-workspace

health_checks:
  enabled:
    - broken_imports
    - dead_exports
    - circular_deps
    - secrets
  severity_overrides:
    no_console_log: P2
    unused_imports: P3

ignored_paths:
  - vendor/
  - generated/

languages:
  typescript:
    strict_mode: true
  rust:
    edition: "2021"

team.yml: Top-Level Fields

Field	Type	Default	Description
plugins	array of strings	[]	Plugin IDs to enable for every team member. Each entry is a plugin identifier (e.g., "react-best-practices"). Appended to any personal plugins.
health_checks	object	(see below)	Health check configuration shared across the team.
ignored_paths	array of strings	[]	Gitignore-style path patterns to exclude from indexing. Appended to per-user ignored paths.
languages	map of string to object	{}	Per-language configuration overrides. Keys are language identifiers; values are freeform maps consumed by language plugins.

team.yml: health_checks Fields

Field	Type	Default	Description
health_checks.enabled	array of strings	[]	Explicit list of health check IDs to enable. When empty, Forge’s default check set is used. Merged with the user’s personal enabled checks (union, not replacement).
health_checks.severity_overrides	map of string to string	{}	Per-check severity overrides. Keys are check IDs; values are "P0", "P1", "P2", or "P3". Example: no_console_log: P2 downgrades the check from its default severity.

team.yml: languages Fields

Language-specific keys are consumed by language plugins. Unknown keys are ignored silently. Common examples:

Language	Key	Type	Description
typescript	strict_mode	bool	Enable strict TypeScript checks in relevant plugins.
rust	edition	string	Rust edition (e.g., "2021").

---

Built-In Health Check IDs

These are the check IDs valid in health_checks.enabled and health_checks.severity_overrides:

ID	Default Severity	Description
broken_imports	P1	Import specifiers that do not resolve to any indexed file.
dead_exports	P2	Exported symbols with no known importers.
circular_deps	P1	Circular import chains.
secrets	P0	Hard-coded API keys, tokens, and credentials.
no_console_log	P3	console.log calls left in production code.
unused_imports	P3	Imported symbols that are never referenced.

---

Configuration File Locations Summary

File	Scope	Checked In
~/.forge/config.toml	All repos on this machine	No (personal)
<repo>/.forge/config.toml	This repo, this user	No (personal)
<repo>/.forge/team.yml	This repo, all users	Yes
~/.forge/license.json	Machine license state	No
~/.forge/stats.json	Local usage statistics	No
~/.forge/heartbeat.json	Heartbeat cache state	No
~/.forge/community_usage.json	Community Mode rate limit state	No