Team Shared Configs

import { Aside, Tabs, TabItem } from ‘@astrojs/starlight/components’;

Individual developers have personal Forge configs at ~/.forge/config.toml. These are intentionally not committed — they contain machine-specific paths and personal preferences. Team-wide rules go in .forge/team.yml, which is committed to the repo and applies to everyone who clones it.

What belongs in team.yml

Team config is for rules and constraints that should be consistent across the team:

• Health check severity overrides
• Custom plugin definitions
• Shared ignored paths
• Language detection overrides
• Entry points for the repo

Personal preferences (index storage path, preferred output format, license key) stay in ~/.forge/config.toml.

Create .forge/team.yml

Create .forge/team.yml in the repo root:

.forge/team.yml

# Team-wide Forge configuration — committed to the repo.
# Personal settings go in ~/.forge/config.toml (not committed).

version: "1"

index:
  ignored_paths:
    - node_modules
    - dist
    - build
    - .next
    - coverage
    - "**/*.min.js"
    - "**/*.test.ts"
    - "**/*.spec.ts"

  entry_points:
    - src/index.ts
    - src/main.ts

health:
  # Promote dead_export from P1 (error) to P0 (critical) for this team
  severity_overrides:
    dead_export: P0

  # Disable a specific check entirely
  disabled_checks:
    - unused_dependency   # too many false positives in this monorepo

plugins:
  - path: .forge/plugins/no-console-log.yaml
  - path: .forge/plugins/no-any-type.yaml

After creating team.yml, re-run forge index to apply the new configuration.

Config precedence

Forge merges configs in this order (later wins for conflicts):

1. Built-in defaults
2. ~/.forge/config.toml (user global)
3. .forge/config.toml (repo-local, usually not committed)
4. .forge/team.yml (team-shared, committed)

Team config wins over user config for shared concerns. This means a developer can’t accidentally override a team rule by adding something to their personal config.

The exception: if a key is only present in user config and not in team config, the user config value applies. Team config doesn’t reset everything — it only overrides the keys it defines.

Team tier is required to use `.forge/team.yml`. Solo and Community users can use `.forge/config.toml` per-repo instead.

Severity overrides

Adjust how strictly Forge treats specific finding types for your team:

health:
  severity_overrides:
    # Make broken imports fail CI (P0 blocks CI with --fail-on-p0)
    broken_import: P0

    # Downgrade circular deps to warning (your architecture has intentional cycles)
    circular_dep: P2

    # Disable entirely — not relevant to this codebase
    dead_export: disabled

Available severities: P0, P1, P2, P3, disabled.

Disabled checks

Disable individual checks that generate too much noise for your codebase:

health:
  disabled_checks:
    - unused_dependency
    - missing_return_type   # TypeScript project uses "noImplicitAny" but not explicit returns

This is preferable to setting a severity to disabled when you want to disable a whole category.

Plugin references

Reference custom health check plugins. The path is relative to the repo root:

plugins:
  - path: .forge/plugins/no-console-log.yaml
  - path: .forge/plugins/no-any-type.yaml
  - path: .forge/plugins/no-direct-db-access.yaml

See Write a Custom Health Check for how to create these files.

Language settings

Override language detection for files that don’t use standard extensions:

languages:
  overrides:
    - pattern: "scripts/**/*.cjs"
      language: javascript
    - pattern: "infra/**/*.ts"
      language: typescript
      # Include infra TypeScript files even if they're outside src/

Example: backend API team

A team config for a TypeScript Node.js API with strict standards:

version: "1"

index:
  ignored_paths:
    - node_modules
    - dist
    - coverage
    - "**/*.test.ts"
    - "**/__mocks__"
  entry_points:
    - src/server.ts
    - src/cli.ts

health:
  severity_overrides:
    broken_import: P0
    circular_dep: P0
    dead_export: P1
  disabled_checks: []

plugins:
  - path: .forge/plugins/no-console-log.yaml
  - path: .forge/plugins/no-process-exit.yaml
  - path: .forge/plugins/require-error-handling.yaml

Verify team config is loaded

forge health --explain-config

Expected output:

forge: config sources loaded
  Built-in defaults
  ~/.forge/config.toml (user)
  .forge/team.yml (team) ← this confirms team.yml is active

Active settings:
  ignored_paths:  12 entries (8 from team.yml, 4 from user config)
  entry_points:   2 entries (from team.yml)
  plugins:        2 loaded (from team.yml)
  severity overrides: broken_import=P0, circular_dep=P0

Common pitfalls

team.yml ignored silently Forge requires the file to be named exactly .forge/team.yml (with a leading dot on the directory). A file at forge/team.yml or .forge/Team.yml will not be loaded.

Conflicts between user and team config If a developer has a severity_overrides in their ~/.forge/config.toml for the same finding type as team.yml, team.yml wins. This is intentional. If a developer needs to work around a team rule, they should raise it with the team rather than overriding locally.

Plugin paths don’t resolve Plugin paths in team.yml are relative to the repo root, not to .forge/. A plugin at .forge/plugins/my-check.yaml is referenced as path: .forge/plugins/my-check.yaml, not path: plugins/my-check.yaml.

Related guides

• Write a Custom Health Check
• Configure Monorepo
• CI Cached Indexes