Composable system prompts for AI coding agents.
Your AGENTS.md shouldn't be a 500-line wall of text that you copy between repos and pray stays consistent. Loadout treats agent guidance the way package managers treat dependencies: small, focused fragments that you compose into purpose-built profiles.
Most teams manage their AI agent prompts by hand as one monolithic CLAUDE.md or AGENTS.md per repo, maintained through copy-paste. This breaks down fast:
- Drift. The same coding conventions exist in twelve repos, worded twelve different ways.
- Bloat. Every agent sees every instruction, whether it's relevant to its task or not.
- No specialization. A code-review agent and a feature-development agent have fundamentally different jobs, but they read the same prompt.
Loadout lets you write prompt guidance once as markdown fragments, then compose them into loadouts. Loadouts are named profiles that produce the final AGENTS.md, CLAUDE.md, and GEMINI.md files your tools already read.
fragments/
├── universal/
│ ├── naming-conventions.md
│ └── code-review-ideology.md
├── kotlin/
│ └── kmp-project-structure.md
└── testing/
└── behavior-first-testing.md
# One loadout for day-to-day development
loadout create engineer --desc "Kotlin-Multiplatform Engineer" \
--fragment fragments/universal/naming-conventions.md \
--fragment fragments/kotlin/kmp-project-structure.md \
--fragment fragments/testing/behavior-first-testing.md
# Another for code review, with different priorities
loadout create code-reviewer \
--clone engineer \
--desc "Ideology-Aware Code Reviewer" \
--fragment fragments/universal/code-review-ideology.md
# Switch contexts in one command
loadout use code-reviewerEach loadout use or loadout sync regenerates the output files. Your agent reads the right guidance for the right job.
brew tap noheltcj/loadout
brew install loadoutPrebuilt binaries for macOS (arm64/x64), Linux (arm64/x64), and Windows (x64) are available on the releases page.
git clone https://github.com/noheltcj/loadout.git
cd loadout
# Supported targets: LinuxArm64, LinuxX64, MacosArm64, MacosX64, MingwX64
./gradlew linkReleaseExecutableMacosArm64
./build/bin/macosArm64/releaseExecutable/loadout.kexe --help# Initialize Loadout in your project
loadout init
# In shared mode (the default), that gives you:
# - A starter fragment at fragments/loadout-architect.md
# - A "default" loadout that includes it
# - Generated AGENTS.md, CLAUDE.md, and GEMINI.md
# - .githooks/ with post-checkout and post-merge scripts (committed)
# - git configured to use .githooks/ as the hooks pathFrom here, the workflow is: write fragments → compose loadouts → sync outputs.
# See what's active
loadout
# List all loadouts
loadout list
# Create a new loadout
loadout create <name> --desc "Usually the purpose of the loadout / profile"
# Compose fragments
loadout link path/to/fragment.md --to <loadout>
loadout unlink path/to/fragment.md --from <loadout>
# Switch to a different loadout
loadout use <name>
# Regenerate outputs after editing fragment content
loadout sync
# Preview output without writing files
loadout use <name> --std-out
# Delete a loadout
loadout remove <name>
# View or set the repository default loadout (used by auto-sync hooks)
loadout config
loadout config --default-loadout <name>Loadout manages three things:
| Concept | What it is |
|---|---|
| Fragment | A markdown file containing focused guidance on one concern. |
| Loadout | A named profile that references a set of fragments. |
| Output | The generated AGENTS.md / CLAUDE.md / GEMINI.md your agent reads. |
Fragments live wherever makes sense:
- Simple projects or project-specialized fragments may keep them in-repo under
fragments/. - For teams or multi-repository projects, it's recommended to keep fragments in a shared, version-controlled fragment library. This enables sharing of common conventions across projects.
loadout init # shared mode (default) - loadout definitions are committed
loadout init --mode local # local mode - everything stays gitignoredShared mode lets a team standardize on the same set of agent profiles. Local mode is for personal workflows where each developer curates their own.
.loadout.jsonstores tracked repository settings such as the default loadout for hook-driven sync..loadout.local.jsonstores local-only runtime state such as the active loadout and last composed content hash.
In shared mode, loadout init commits .githooks/ hooks alongside your loadout definitions. On every branch checkout and merge, those hooks run loadout sync --auto to regenerate the output files from whichever loadout is set as the repository default.
The reason this matters: AGENTS.md, CLAUDE.md, and GEMINI.md are gitignored. A fresh clone or a new worktree won't have them. Without the hooks, every developer (and every agent session) would need to run loadout sync manually before getting the right context.
This is especially relevant when using agentic tools like Codex or Antigravity that spin up isolated git worktrees. Each worktree gets the correct guidance files on first checkout — no manual setup, no missing context.
Set the default loadout the hooks will use with:
loadout config --default-loadout <name>If no default is configured, --auto is a no-op and the hooks exit cleanly.
The value compounds as the fragment library grows:
- Reuse across projects. Write your naming conventions, architecture rules, or review ideology once. Reference them from any repo.
- Specialize per task. A loadout for feature work includes testing guidance. A loadout for code review includes review ideology. Neither carries the other's baggage.
- Evolve independently. Update a fragment or checkout a new fragment library commit and
loadout syncwill propagate the change. - Keep it readable. Each fragment is a short, self-contained markdown file focused on a single concern. They should be easy to review and refine.
The CLI is built with Kotlin Multiplatform targeting native executables. The codebase follows a clean-architecture layout:
src/commonMain/kotlin/cli/- Command definitions and output renderingsrc/commonMain/kotlin/domain/- Entities, services, and use casessrc/commonMain/kotlin/data/- Repository implementations and serializationsrc/nativeMain/kotlin/- Native entrypoints and platform wiring
# Run the test suite
./gradlew checkContributions are welcome.
- Fork the repo.
- Create a feature branch:
git checkout -b feature/your-feature. - Run tests:
./gradlew check. - Open a PR with a clear description and small, focused commits.