Skip to main content
gaal reads configuration from up to three files. They merge in a strict order so a workspace gaal.yaml checked into source control can never escalate machine-wide settings.

​
The three scopes

PriorityScopeFile
1 (lowest)System/etc/gaal/config.yaml
2User$XDG_CONFIG_HOME/gaal/config.yaml (defaults to ~/.config/gaal/config.yaml on Linux/macOS, %AppData%\gaal\config.yaml on Windows)
3 (highest)Workspacegaal.yaml in the current working directory, or whatever --config points at
Higher-priority files override lower ones field by field.

​
What overrides what

Most fields are merged with workspace winning over user winning over system:
  • repositories, workspace entries replace user entries with the same map key.
  • skills, the workspace list replaces the user list (no per-entry merging, pick one scope or the other).
  • mcps, same as skills: workspace list replaces user list.
The exception is telemetry, which is scope-restricted.

​
Scope-restricted fields

telemetry can be set in the user or system file but not in a workspace file. If a workspace gaal.yaml sets telemetry:, gaal ignores the value and prints a warning. This rule exists so that committing a gaal.yaml to a public repo can never opt anyone in to telemetry. Telemetry is a per-user choice, made explicitly on first run.

​
Where you’d put what

SettingBest scopeWhy
Personal helper skills installed everywhereUserSurvives across projects without committing a global file.
Project-specific skills (codebase reviewer, custom MCP)WorkspaceLives with the repo so contributors get the same tools.
MCP servers shared across all your projects (filesystem, git)UserDefined once, not per-project.
Telemetry opt-inUserThe only place the value is honoured.

​
Inspecting the merged config

gaal status reports the resolved configuration as gaal sees it after merging. gaal doctor reports the source file for each entry. 
$ gaal doctor
config sources:
  workspace  ./gaal.yaml
  user       /home/you/.config/gaal/config.yaml
  system     (none)

​
Overriding the lookup

Force a specific file with --config: 
gaal --config /path/to/custom.yaml sync
When --config is set, the user and system files are still merged underneath unless the file you passed sets the same fields.

The gaal.yaml file

Telemetry

Sharing across machines

gaal doctor