Config Schema

.ctxo/config.yaml is the committed team-level configuration for Ctxo. It is optional; every field has a default and the file itself can be absent. When invalid, the loader warns and falls back to defaults (warn-and-continue). Field-level problems surface through ctxo doctor.

File location

<repo-root>/.ctxo/config.yaml

The .ctxo/ directory also holds the committed index/ tree and the gitignored .cache/ SQLite. See ctxo config.yaml for the CLI-facing view of this file.

Full schema

version: "1.0"

stats:
  enabled: true

index:
  ignore:
    - "packages/**/fixtures/**"
    - "tools/legacy-*/**"
  ignoreProjects:
    - "packages/experimental-*"
    - "examples/*"

gate:
  enabled: true
  sensitivity: balanced

Fields

Field	Type	Default	Purpose
version	string or number	"1.0"	Schema version marker. Forward-compatible; unknown values are accepted.
stats.enabled	boolean	true	Session recording opt-out. Set false to disable local stats capture.
index.ignore	string[]	[]	Picomatch globs applied to file paths after git ls-files.
index.ignoreProjects	string[]	[]	Picomatch globs applied to workspace roots. Skipped workspaces are never enumerated.
gate.enabled	boolean	true	Enable or disable the safe-edit guard PreToolUse hook.
gate.sensitivity	strict | balanced | lenient	balanced	How aggressively the guard flags high-impact symbols.

gate.sensitivity levels

Level	PageRank percentile	Min dependents floor	Use case
strict	top 30%	2	Large shared codebases; flag nearly anything with dependents
balanced	top 15%	3	Default - catches genuinely high-impact symbols without too much noise
lenient	top 5%	5	Only block edits to truly critical symbols (god nodes, public APIs)

Run ctxo gate --preview after changing sensitivity to see which symbols would be flagged.

Unknown fields at the root are ignored for forward compatibility. Unknown fields inside the stats, index, or gate sections are rejected as schema violations (typos surface immediately).

Glob matching rules

index.ignore and index.ignoreProjects both use picomatch with { dot: true }.

• Patterns are matched against repo-relative, forward-slash paths. Backslashes are normalised before matching.
• index.ignore runs per file, after the git-tracked file list is produced.
• index.ignoreProjects runs against workspace roots during discovery. A matched workspace is never visited, and its plugin dependencies are never imported.

index:
  ignore:
    - "**/*.generated.ts"      # extension match anywhere
    - "packages/**/dist/**"    # nested directories
    - "!packages/core/dist/**" # negation also supported

Defaults

When config.yaml is missing, unreadable, or invalid, Ctxo uses:

version: "1.0"
stats:
  enabled: true
index:
  ignore: []
  ignoreProjects: []

Error handling

Condition	Behaviour
File missing	Silent; defaults used.
YAML parse error	ctxo doctor emits a warning; defaults used.
Schema violation (unknown field in stats/index, wrong type)	ctxo doctor emits a fail; defaults used.
Invalid glob pattern	ctxo doctor emits a warning; the bad pattern is dropped, valid siblings still apply.

All failure modes follow the warn-and-continue rule: indexing never aborts because of a config problem. The loaded config is available to core code as a LoadedConfig record with errors and invalidGlobs arrays for diagnostic consumers.

TIP

Run ctxo doctor after editing config.yaml to surface every warning and fail in one report.

WARNING

Do not use index.ignore to exclude files from a language plugin's parser. Plugins operate on the files Ctxo hands them; filtering happens at the index layer, not at the parser.

See also

• ctxo config.yaml - CLI-facing summary
• ctxo doctor - surfaces config warnings and schema fails
• ctxo index - consumer of the index.ignore list