loadout

Purpose

Loadout is an adaptive context engine for AI coding agents. Its premise is simple: different work needs different context, and you should not give the agent the same set of content every time. After installation, you create Loadouts for common work scenarios, and when you start an agent (such as load claude .), context and workflows are dynamically injected. A Loadout is a kit equipped before going on duty—your conventions, tools, and tone. Whether you are in a Rust repository, a Next.js app, or on a bare server with no repository at all, Loadout automatically picks the appropriate kit. The AGENTS.md in a project describes the repository itself, while what Loadout carries is what you bring across projects, across machines, and across agents.

Main Capabilities

• Context Kits (Loadout): named kits composed of several fragments (Fragments), bound to one or more targets (Targets). When a target matches, the kit's fragment list is rendered.
• Fragments: reusable units of guidance or context, which can be static text or dynamic output from built-in providers or shell commands.
• Targets: the coarse-grained project or environment types that Loadout detects, including rust, node, bun, nextjs, go, python, java, ruby, php, swift, dotnet, and machine (used when not inside a repository, suitable for system administration and DevOps).
• Selection Mechanism: each context is equipped with only one Loadout; kits are not merged or stacked. Composition happens inside the selected kit, through its fragment list. Selection is deterministic and inspectable, not decided by an LLM, and the agent only sees the final rendered overlay.
• Workflow: a workflow carries your process—how you want to work, consistently across all agents. Loadout provides a fixed set of six slash commands: /loadout:explore, brainstorm, plan, implement, verify, ship. The specific meaning of each step is determined by the workflow equipped by the kit. Three official built-in processes are provided: Superpowers, spec-driven (Spec Kit / Kiro), and Every's compound engineering, whose skill files are included as-is; you can also build your own. Workflows take effect only globally and are not enforced; they are merely guidance rendered to each agent. Files can be passed between stages (for example, plan writes plan.md, and implement reads it).
• Plan Preview and ReviewReview: load plan turns the development plan written by the agent into a reviewable page, rather than a big block of chat text. The workflow is: the agent writes a structured plan.json → load plan check validates it → load plan render renders a self-contained plan.html and opens it in the browser → you comment item by item on tasks, phases, risks, and open questions → the Copy feedback button assembles the comments into a structured document, which you paste back to the agent so it can revise and re-render. Rendering is deterministic (the same plan.json and Loadout version produce byte-for-byte identical HTML), and self-contained, with no dependency on CDNs or external requests.
• load studio: a local Web UI that listens only on localhost, used to manage the snippet and kit library. It is a visual editor on top of TOML configuration, not a hidden database; it does not write to disk until you review and apply the staged diff. It can be used to create and edit snippets, compose kits, assign to targets, browse and build workflows, preview generated overlays, run dynamic snippet previews, and review diffs before applying. It has a built-in starter pack gallery, which detects your tech stack and marks recommendations; when applied, it copies snippets into your library, with no auto-activation magic.
• Cross-machine sync: snippets and kits exist only globally; sharing means syncing the global configuration; when starting the agent (load claude), it first pulls the latest configuration before rendering. The private local.toml (hostname, host class, machine-specific values) stays local and is not synced. Syncing requires git on the machine, which minimal images often do not include, so you can first apt install git.
• Migration capabilities: the built-in loadout-migrate skill can read your existing global agent instructions and convert them into Loadout snippets and required kits, without affecting the original files. There are also loadout-remember (save cross-project preferences mentioned in a session as snippets), loadout-import-workflow (convert command/skill kits from other repositories into Loadout workflows), and loadout-plan-preview (drive the plan preview loop). Skills follow the cross-agent SKILL.md format, so the same installation can be used in Claude Code, Codex, opencode, and Cursor.
• Security design: the generated overlay is an ordinary file for the agent to read, not an enforced policy. It only allows whitelisted environment variables, a blacklist of secret names and token redaction, atomic writes, gitignored artifacts, managed marker blocks, context hashes, and --dry-run previews. You can run load doctor to check the configuration.

Usage

When Node is available, one command installs the CLI (it will ask first) and opens studio: after installation, you can use load studio to reopen. Then use load claude and other commands to start the agent with context. You can also directly install a precompiled binary, with no Rust toolchain required (macOS and Linux; Windows uses WSL). Via npm, @ellery/loadout is a thin bootstrap program that shows what it will do and, after obtaining consent, runs the same installation script, then hands off to the load CLI; machines that already have loadout will check for a new version and ask whether to update. Installer-based installations can be updated in place with load update ; you can also from source cargo install --git … Or clone and then cargo build.

There are only three official installation channels: GitHub releases, the source code of this repository, and npm. Binaries from any other source should be treated as untrusted. There is currently no official Homebrew tap or other third-party package.

Common commands include load, load studio, load plan (check/render), load doctor, load --help (including global flags such as --cwd, --verbose, and --dry-run). Committed shared files such as AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md will never be modified; only local, gitignored paths are used.

Use cases

• Switching between repositories with different technology stacks (Rust, Next.js, Go, Python, etc.) and wanting the agent to automatically obtain the corresponding conventions and tool context.
• System administration and DevOps scenarios, working on bare machines without a repository (the machine target).
• Maintaining consistent context and workflows across Claude, Codex, Cursor, opencode, and Copilot.
• Needing a structured, reviewable development plan rather than a chat-style plan.
• Migrating existing global agent instructions to unified management.

Limitations

• Only one Loadout is equipped per context; suites are not merged or stacked.
• Workflows only take effect globally and are not enforced; they are merely guidance that is rendered.
• The generated overlay is an ordinary file for the agent to read, not an enforced policy.
• Cross-machine synchronization depends on git already being available on the machine.
• The supported platforms for precompiled binaries are as described in the materials (macOS and Linux; use WSL on Windows).
• The materials do not provide specific information such as pricing, billing models, or performance metrics.
• Complete documentation is located in the repository's docs/ directory, covering concepts, configuration, security and trust, architecture, extension and testing, and more. The project is under the MIT license.