Configure your agents across projects¶

Global configuration holds instructions, permissions, skills, and tools you want available across projects. Project-specific context belongs in project configuration or a template.

Create a source¶

Choose a directory for your configuration:

loadout init global ~/agent-config

For a new directory, Loadout creates a nested loadout/ directory:

~/agent-config/loadout/
├── README.md
├── loadout.toml
├── mcp.toml
└── permissions.toml

mcp.toml holds a commented example until you define a server; commented out, it changes nothing. init writes permissions.toml unless Codex is the only harness and has no ~/.codex/rules/permissions.rules yet. A missing permissions.toml means the same as an empty one. README.md shows the full layout and how to add hooks, plugins and settings. Anything init adopts from your existing agent configuration lands beside these: instructions, settings, hooks, plugins and skills, each in its own directory.

init then renders, as the first sync: when loadout reproduces your existing files it writes them and says so, and when it would change one it shows the diff and asks first. There is no need to run loadout sync straight after init.

It also writes the machine configuration at ~/.config/loadout/config.toml, or $XDG_CONFIG_HOME/loadout/config.toml when XDG_CONFIG_HOME is set. That file points at ~/agent-config/loadout.

If the directory you pass already contains loadout.toml, Loadout adopts it directly. If both the direct and nested locations contain manifests, it refuses to choose between them. An existing machine configuration is protected from reinitialisation.

Choose your agents¶

init global writes one block per harness, holding what it adopted. Add to those blocks rather than replacing the file, which would drop what was adopted. A source that adds shared instructions looks like this:

[[source]]
name = "personal"
path = "."

[all]
instructions = ["workflow"]

[claude]
[codex]

Create ~/agent-config/loadout/instructions/workflow.md:

# How I work

Keep changes focused.
Explain trade-offs when there is more than one reasonable approach.
Verify your work before reporting completion.

Edit the source's permissions.toml:

[shell]
allow = ["git status", "git diff"]
ask = ["git commit"]
deny = ["git push"]

[all] supplies defaults to the agents you declare. Adding [opencode] or [pi] opts that agent in too. It does not enable an undeclared agent.

Sync and check¶

loadout sync --global
loadout check --global

Loadout writes to each selected agent's global configuration directory. The destinations follow the harness environment variables listed in the support reference.

If you are adopting an existing setup, first move the configuration you want to retain into the source. Sync may refuse an output containing changes it cannot recognise. Review its diff and follow protected edits.

Keep the source portable¶

Version-control the configuration source using your normal git workflow. On another machine, clone it and point Loadout at the directory containing loadout.toml:

loadout init global ~/agent-config/loadout
loadout sync --global

The machine configuration itself is local state. It may select a profile as well as the source:

source = "~/agent-config/loadout"
profile = "focused"

Create focused.toml beside loadout.toml before selecting it. See profiles.

Disambiguate a fragment name¶

If several sources offer the same fragment name, loadout does not pick one: it refuses the unqualified name and lists the candidates. Qualify it with the source that should win:

instructions = ["personal/workflow"]

A command for inspecting resolution directly is not available in 1.0.

Configure through your agent¶

Loadout ships a version-matched skill:

loadout integrate skill install
loadout integrate skill status

Installation shows the destination and asks for confirmation. Add --yes for non-interactive installation, or --source NAME when several sources offer skills. It vendors the skill into your global source and syncs the selected profile.

Restart a running agent session so it discovers the installed skill. Invoke loadout through that agent's skill syntax and describe the configuration change you want.

The skill's --personal, --project, and --global scope vocabulary belongs to the skill. The CLI expresses scope as the init project / init global subcommands; every other command keeps --root or --global and does not accept --personal or --project.