Your agent is ignoring half the skills you installed.

loadout keeps every skill installed and shows your agent only the ones for today's work. Switch the visible set by task — product, design, research, coding. Crash-safe, one-command rollback.

The problem

You've installed more skills than your agent can use. ~/.claude/skills/ is full. Codex too. Past a certain count, your harness silently drops some — they're installed, but invisible to the model. You end up:

• Manually moving folders in and out of skills/
• Tolerating the clutter and hoping the model picks the right one
• Keeping fewer skills installed than you actually want

loadout fixes this without deleting anything. Every skill stays installed. Only the active set is visible to the harness; the rest sits in a pool ready to swap in.

~/.claude/skills/           ← Claude active set
~/.codex/skills/            ← Codex active set
~/.agents/skills/           ← shared agents active set
~/.loadout/pool/<harness>/  ← pool: installed but hidden
~/.loadout/mds/<mode>/      ← per-mode CLAUDE.md / AGENTS.md (optional)
~/.loadout/modes.yaml       ← named subsets ("product", "design", ...)
~/.loadout/state.json       ← which modes are active right now

A mode is a named subset of skills. Activating a mode moves its skills from pool → active. Deactivating moves them back. Files are moved with atomic renames and a lockfile — if a swap is interrupted, the next command resumes it.

Why use it

• You keep every skill. Nothing is deleted; everything is reversible.
• Crash-safe. Atomic moves, lockfile, resume-on-interrupt. Ctrl-C mid-swap is fine.
• One escape hatch. loadout restore-all puts everything back where the harness can see it.
• Multi-harness. Claude Code, Codex, and shared ~/.agents/skills harnesses out of the box; one manifest covers them all.

Borrow other people's setups

Want to play with a curated skill pack (gstack, a friend's dotfiles, anything) without their skills cluttering yours?

loadout save mine        # snapshot what you already have
# ...install the other pack...
loadout save theirs      # snapshot the new state

loadout use mine         # flip back to your setup
loadout use theirs       # flip to theirs

Borrow setups freely, your workflow stays intact.

Install & first run

npm install -g @ivcota/loadout
loadout init              # scan harnesses, seed 'default' mode with everything
loadout status            # show active modes + per-harness skill counts

Or try it without installing globally:

npx @ivcota/loadout status

Requires Node 20+.

init writes ~/.loadout/modes.yaml and ~/.loadout/state.json. It does not move any files. Codex skills are managed at ~/.codex/skills; ~/.agents/skills is managed separately as the shared agents harness.

Daily workflow

# I'm switching to product work — collapse my visible skills to just product
loadout use product

# Need design skills too for this session — stack them on
loadout on design

# Done with design — drop it, keep product
loadout off design

# Take me back to my default set
loadout reset

# Where am I right now?
loadout status

# I've manually tuned my active set and want to save it as 'deep-work'
loadout save deep-work

# Pick skills for a mode in an interactive checkbox UI
loadout edit research

# Quick edits to modes.yaml without the TUI
loadout new   research
loadout add   research investigate
loadout rm    research old-skill
loadout sync               # pick up newly installed skills into 'default'
loadout sync  research     # ...or into a specific mode
loadout delete throwaway

Mode instruction files (CLAUDE.md / AGENTS.md)

A mode can bundle a per-harness instruction file alongside its skills. When you activate a mode, loadout materializes the right CLAUDE.md / AGENTS.md at the harness's canonical path — so switching modes flips both the visible skills and the harness's standing instructions in one move.

# Author a mode's MDs from existing files
loadout md-set coding claude ./CLAUDE.coding.md
loadout md-set coding codex  ./AGENTS.coding.md

# Or capture whatever's currently live as the mode's MD
loadout use coding
# ...hand-edit ~/.claude/CLAUDE.md until it's right...
loadout save coding --md           # snapshots the live MDs into the mode

# Inspect / remove
loadout md-show  coding claude
loadout md-unset coding claude

Resolution is last-applied-wins: walking active_modes from last to first, the first mode that supplies an MD for a given harness wins. If no active mode supplies one, loadout restores the baseline snapshot it took on loadout init. Claude reads ~/.claude/CLAUDE.md, Codex reads ~/.codex/AGENTS.md; the shared agents harness has no instruction-file convention and is skipped. After a swap, loadout prints a one-line hint reminding you to restart the harness session if its instruction file changed.

Task presets

# Coding session
loadout use coding
loadout on tdd

# Writing / marketing
loadout use marketing
loadout on hormozi-ad-factory

# Research dive
loadout use research

Safety & escape hatches

You can preview any destructive command:

loadout use product   --dry-run    # show planned moves, change nothing
loadout restore-all   --dry-run
loadout uninstall     --dry-run

If something feels off:

loadout doctor              # report invariant violations (manifest/state/fs)
loadout doctor --fix        # auto-repair safe issues (preview with --fix --dry-run)
loadout restore-all         # move every pool skill back to active; keep modes.yaml
loadout uninstall           # restore-all + remove ~/.loadout entirely

If a swap is mid-flight when you re-run any command, loadout drains it first. To undo it explicitly:

loadout use product --rollback   # revert the in-progress op

What doctor catches (and --fix resolves)

| Issue | Severity | Auto-fix | |---|---|---| | missing-active-skill — mode expects skill in active, but it's in pool | error | ✓ moves it back | | unknown-active-mode — state.json names a mode missing from modes.yaml | error | ✓ drops it | | stale-lock — orphaned lock from a crashed process | warn | ✓ clears it | | unknown-skill — mode references a skill not installed anywhere | warn | manual | | orphan-pool-skill — pool has a skill no mode references | warn | manual | | md-drift — live instruction file disagrees with the recorded sha (hand-edited since last swap) | warn | manual | | missing-mode-md — state.live_mds points to a mode MD that's no longer on disk | warn | manual |

doctor exits with code = remaining-issue-count, so it's CI-friendly.

How it works (one paragraph)

Each harness adapter owns an active dir (Claude: ~/.claude/skills, Codex: ~/.codex/skills, shared agents: ~/.agents/skills) and a pool dir (~/.loadout/pool/<harness>/). A mode is a list of skill folder names. Activating a mode plans a set of activate moves (pool → active) for skills not yet active; deactivating plans deactivate moves. Plans are written to state.json as an in_progress block before any rename, then drained one move at a time. On crash, the next command sees in_progress and resumes. Cross-filesystem renames fall back to copy-then-delete.

Dev

npm install
npm test
npm run typecheck
npm run build
node dist/cli.js --help

Stack: TypeScript (Node 20+, ESM) · Effect-TS (effect, @effect/cli, @effect/platform) · Ink for the TUI · proper-lockfile, write-file-atomic, fs-extra for crash-safe swaps · Vitest + @effect/vitest + fast-check for tests · tsup for build.

Links

• npm
• GitHub
• Issues

License

MIT