How gaal works

gaal is a small, opinionated state engine. Once you understand the four moving parts you understand the whole product.

​

The four moving parts

Every gaal command runs the same four-stage pipeline.

1. gaal.yaml, the source of truth. You write it (or generate it with gaal init) and commit it to your dotfiles. Everything downstream reads from this file.
2. Audit, read the filesystem. gaal scans the local filesystem to discover what’s already there: every installed agent, every skill on disk, every MCP entry in every agent’s JSON config. Audit writes nothing.
3. Plan, diff desired vs actual. gaal compares the desired state from gaal.yaml against the actual state from the audit and computes the work to do. gaal sync --dry-run stops at this stage and prints the plan.
4. Sync, apply through renderers. The plan executes through per-agent renderers, small adapters that know each agent’s native file layout and config format. They write to .claude/skills/*, .cursor/mcp.json, ~/.codex/skills/*, and so on.

​

The agent registry

gaal ships with a built-in registry of every supported agent: where its skills live, where its MCP config file is, and how its package manager stores extensions. The registry is what makes agents: ["*"] work, when you say “install this skill in every detected agent,” gaal walks the registry, checks which agents are actually installed, and installs only into those. You can extend the registry with your own entries. See Custom agents.

​

Resource types and guarantees

Every entry in gaal.yaml falls into a small set of resource types, and each type has a clear boundary: The MCP guarantee is the one that matters most: gaal will not clobber your agent config. It reads, modifies the MCP section in place, and writes back.

​

Scopes

Every config file lives at one of three scopes, and they merge in a strict order: A workspace gaal.yaml overrides the user file overrides the system file. Some keys (like telemetry) are restricted to the user/system scope so a checked-in workspace file can’t change them. See Scopes for the full rules.

​

What gaal doesn’t do

• It doesn’t run your agents. gaal just makes sure each agent has the right files in the right place.
• It doesn’t proxy or intercept LLM calls. The runtime path is between your agent and its model provider.
• It doesn’t push state anywhere. gaal today is local-only, your gaal.yaml and the files it touches stay on your machine. (If you want shared state across a team, that’s what Community Edition will be for.)

​

Next