Skip to content

One setup, two agents

This walkthrough creates a small project configuration for Claude Code and Codex. You will write the instructions once, render both agents' files, and make a change that reaches both.

Install

Install uv, then install Loadout directly from its repository:

uv tool install --python 3.13 git+https://github.com/nielsmadan/loadout.git
loadout --help

Loadout requires Python 3.13 or newer. uv can provision Python for the tool environment. If the shell cannot find loadout, run uv tool update-shell and open a new terminal.

For an editable development installation, clone the repository and run just install-editable there.

Create a project configuration

Start in a new directory to try the workflow:

mkdir loadout-demo
cd loadout-demo
loadout init project --harness claude --harness codex

This creates loadout/config.toml and loadout/permissions.toml, renders each agent's generated files and lists them in .gitignore. Project setup works without a global configuration.

Replace the freshly created loadout/config.toml with:

loadout/config.toml
harnesses = ["claude", "codex"]
instructions = ["project"]

Create the instruction directory:

mkdir -p loadout/instructions

Create a fragment:

loadout/instructions/project.md
# Working in this project

Keep changes focused on the requested task.
Run the project's tests before reporting a change as complete.
Explain any checks you could not run.

Write the shared permission file:

loadout/permissions.toml
[shell]
allow = ["git status", "git diff"]
ask = ["git commit"]
deny = ["git push"]

Both permission files are optional. A missing permissions.toml means the same as an empty one: no shared rules, and each agent's permission rules are written empty on the next sync. The personal loadout/permissions.local.toml can stay absent too.

Render both agents' files

init already rendered the setup it found. Now that the source has changed, render again:

loadout sync
loadout check

The resulting files include:

File Consumer
CLAUDE.md Claude Code
AGENTS.md Codex
.claude/settings.json Claude Code's permission rules
.codex/rules/permissions.rules Codex's permission rules

The two instruction documents contain the same fragment. Permission syntax differs because the agents read different formats. Open either agent in this directory to use its generated setup.

loadout check exits successfully when the generated files match their sources.

Change the source once

Add a sentence to loadout/instructions/project.md, then run:

loadout sync
loadout check

Both instruction documents now contain the new sentence. Keep editing the source fragments, rather than the generated CLAUDE.md or AGENTS.md.

Add another agent

Enable OpenCode in the same project by adding it to harnesses in loadout/config.toml:

harnesses = ["claude", "codex", "opencode"]

Then run loadout sync. OpenCode uses the existing AGENTS.md and receives its own opencode.json, and .gitignore gains its generated paths. For OpenCode skills, also follow the setup note.

Use this in an existing repository

Move existing instructions into loadout/instructions/ before enabling instruction generation. Keep existing permission grants in the shared or personal source file. Sync reports protected files that contain edits it cannot attribute to Loadout.

The project guide explains what to commit and how adoption works for a team. The troubleshooting guide covers protected edits.

Where to go next