Skip to main content
charter.yaml is Charter’s repo-root configuration file. It is optional — Charter still runs with built-in defaults when the file is absent. In v1 it exposes two configuration surfaces: policy for score gating and mcp.trustedRemotes for reviewed remote MCP hosts. File location: repo root. Auto-discovered by all Charter commands.

​
Full example

# yaml-language-server: $schema=https://use-charter.dev/schema/charter.schema.json
policy:
  profile: standard    # standard (80), strict (90), or relaxed (60)
  threshold: 85        # optional: overrides the profile's default threshold

mcp:
  trustedRemotes:
    - "api.your-internal-tool.com"
    - "mcp.your-company.com"
The first line is optional but recommended: it points editors (via the YAML Language Server used by VS Code, Neovim, and others) at Charter’s published schema for inline validation and autocomplete. charter init adds it for you.

​
Fields

​
policy.profile
string
Named threshold preset. Accepted values:
ValueThresholdWhen to use
standard80Default for most repos
strict90Security-sensitive or production repos
Default: standard
​
policy.threshold
integer
Explicit numeric threshold. Accepted range: 0–100.Overrides the default threshold for the selected policy.profile. Use this when you want an exact gate that doesn’t map cleanly to the named profiles (for example, 85).
​
mcp.trustedRemotes
string[]
List of remote MCP server hostnames to add to the trusted allowlist for AE-MCP-002.Entries are hostnames, not full URLs. This repo-level list is combined with Charter’s built-in catalog of known vendor-operated hosts. Local origins (localhost, 127.0.0.1) are always exempt and do not need to be listed.

​
Threshold precedence

When multiple threshold sources are present, Charter applies them in this order:
--threshold flag  >  policy.threshold  >  policy.profile default  >  built-in default (80)
If you set both profile and threshold, the threshold value wins. The profile label becomes documentation only.
Example: a CLI invocation always wins over the repo config: 
charter doctor --threshold 95
This gates at 95 regardless of what charter.yaml says, without modifying the file.

​
Validation

Charter fails fast on invalid configuration:
  • Unknown policy.profile values → error at startup
  • policy.threshold outside 0..100 → error at startup
  • Malformed YAML → error at startup

​
Schema

The full JSON Schema is published at https://use-charter.dev/schema/charter.schema.json. Reference it with the # yaml-language-server: $schema=… header shown above for editor validation and autocomplete. Source: web/public/schema/charter.schema.json.

​
See also