Your team's coding agents,
in one command.

Quick start

nix run github:juspay/agent-distro                     # pick from the list
AI_HARNESS=claude nix run github:juspay/agent-distro   # skip the list

To keep the agents installed and updated, see Install and keep updated.

• Systems. x86_64-linux, aarch64-linux, and aarch64-darwin.
• Binary cache. Pass --accept-flake-config to use the cache this flake names;¹ without it, Oh My Pi is built from source.

The chooser

With several profiles, the chooser is master–detail: profiles are tabs in the header, harnesses are the list on the left, and the highlighted harness fills the panel on the right.² ←/→ (or Tab) switch profile, and nothing in the box is ever cut.

Here vanilla/pi is remembered from last time.³

╭─ agent-distro ───────────────────────── juspay · • vanilla ── 6 harnesses ─╮
│ juspay · Juspay skills + Kolu, via Juspay's LiteLLM gateway                │
├──────────────────────────────┬─────────────────────────────────────────────┤
│ ❯   ✓ Oh My Pi       18.7.0  │ Oh My Pi 18.7.0                             │
│     ✓ Codex         0.160.1  │ gateway or own provider · extensions        │
│     ✓ Claude Code   2.1.292  │                                             │
│     ✓ OpenCode      1.18.35  │ Signed in                                   │
│       OpenCode v2    2.0.24  │   LITELLM_API_KEY                           │
│     ✓ Pi              1.0.4  │   anthropic                                 │
│                              │   openai                                    │
├──────────────────────────────┴─────────────────────────────────────────────┤
│ / filter…                                                                  │
╰────────────────────────────────────────────────────────────────────────────╯
↑↓ jk move   ←→ profile   Enter launch   / filter   q quit

By name

For example:

agent-distro codex --version
agent-distro juspay claude --version
agent-distro juspay
agent-distro --list                      # profile harness title version, one row per line
agent-distro --list --json               # the same, as JSON (below)

• Precedence. AI_HARNESS and AI_PROFILE take precedence over positional selections.⁷
• Passthrough. Recognized leading names are consumed; other arguments and everything after -- are passed to the harness unchanged.

One profile

Narrowed to one profile,⁸ the header shows that profile’s name instead of tabs, and the row under it is the same. Versions reflect the packages pinned at build time.⁹

╭─ agent-distro · juspay ────────────────────────────────────── 6 harnesses ─╮
│ juspay · Juspay skills + Kolu, via Juspay's LiteLLM gateway                │
├──────────────────────────────┬─────────────────────────────────────────────┤
│ ❯   ✓ Oh My Pi       18.7.0  │ Oh My Pi 18.7.0                             │
│     ✓ Codex         0.160.1  │ gateway or own provider · extensions        │
│     ✓ Claude Code   2.1.292  │                                             │
│     ✓ OpenCode      1.18.35  │ Signed in                                   │
│       OpenCode v2    2.0.24  │   LITELLM_API_KEY                           │
│     ✓ Pi              1.0.4  │   anthropic                                 │
│                              │   openai                                    │
├──────────────────────────────┴─────────────────────────────────────────────┤
│ / filter…                                                                  │
╰────────────────────────────────────────────────────────────────────────────╯
↑↓ jk move   Enter launch   / filter   q quit

Signed-in marks

✓ marks a harness that can start without a login step; the panel beside it says what was found.¹⁰ A harness with nothing to start from shows a dim Not signed in and no mark.¹¹

AI_GATEWAY=0 puts a gateway harness back on its own provider. This is a launch-time fact: --list and --list --json never carry it.

Keys

• Filtering. The filter line shows the query as typed and how many rows match.¹⁶
• Footer. Lists only the keys that apply at that moment.
• Colour. Follows NO_COLOR and the terminal type.
• Small terminals. Small or unsupported terminals get a numbered list on stderr instead.¹⁷ One that shrinks below that once the box is up shows a notice until it grows again.¹⁸
• No terminal. Without a terminal on stdin, agent-distro says which variables to set instead of drawing anything.

Remembered choice

An interactive selection is remembered in ${XDG_STATE_HOME:-$HOME/.local/state}/agent-distro/last-choice.¹⁹ Next time the default profile still opens, and the remembered profile and harness are marked with •.²⁰

• Updates it. Every interactive choice, including agent-distro <profile>.
• Never updates it. Direct selections: AI_HARNESS, agent-distro <harness>, or agent-distro <profile> <harness>.

Listing as JSON

agent-distro --list --json prints what the chooser draws, on one line, for programs that offer the same choice (such as kolu).²¹ Here it is pretty-printed, with each profile cut to one harness:

{
  "profiles": [
    {
      "description": "Juspay skills + Kolu, via Juspay's LiteLLM gateway",
      "harnesses": [
        {
          "name": "claude",
          "tagline": "Anthropic login · plugin dirs per session",
          "title": "Claude Code",
          "version": "2.1.291"
        }
      ],
      "name": "juspay"
    },
    {
      "description": "Upstream harnesses with your own provider",
      "harnesses": [
        {
          "name": "claude",
          "tagline": "Anthropic login · plugin dirs per session",
          "title": "Claude Code",
          "version": "2.1.291"
        }
      ],
      "name": "vanilla"
    }
  ]
}

Keys within an object are sorted. --list takes no other arguments.²³

Plugins at launch

A profile fixes the plugins its harnesses start with. Put more Agent Plugins directories on AGENT_DISTRO_PLUGINS, and every harness loads them too, in every profile, for that launch:

AGENT_DISTRO_PLUGINS=~/src/my-plugin agent-distro claude
AGENT_DISTRO_PLUGINS=/nix/store/…-kolu/agent-plugin:~/src/my-plugin agent-distro juspay omp

Unset or empty, the launchers behave exactly as they do without this feature.

• Entries. Directories separated by :,²⁴ with empty components ignored.²⁵ An entry that is not a directory fails the launch, naming it.
• Read like a profile’s plugins. Each directory goes through the same reader: an invalid manifest fails the launch with a message naming the field. Lesser problems are reported while the launch goes on.²⁶
• Matched by name, never by version. A plugin whose plugin.json name matches one of the profile’s replaces it; on the variable, the last of a name wins.²⁷
• Translated once. Each harness’s translation of a plugin is cached under ${XDG_CACHE_HOME:-~/.cache}/agent-distro/plugins/<key>/<harness>/.²⁸ An edited checkout is translated again on its next launch.²⁹
• Kept while in use. Each launch marks the translations it uses; a launch that translates something new removes what no launch has used for 14 days.³⁰ With no harness running, removing ~/.cache/agent-distro/plugins is always safe.
• For that launch only. Unset the variable and the harness is back to the profile’s plugins.³¹ Each harness’s README says how.

Install and keep updated

The Home Manager module puts every harness on your PATH and keeps them on the latest build: it checks four times a day,³² installs only what the binary cache already holds, and never compiles.

With Home Manager

{
  imports = [ inputs.agent-distro.homeManagerModules.default ];
  services.agent-distro = {
    enable = true;
    profile = "vanilla"; # default: juspay
  };
}

Home Manager creates the state directory and schedules the updates for you.³³

Without Home Manager

Update by hand:

nix profile install github:juspay/agent-distro#juspay
nix profile upgrade juspay

Or keep the cache-only updates, but drive them yourself:

• agent-distro.lib.mkUpdater (see Library) gives the command and a runnable program.³⁴
• agent-distro.lib.mkShims keeps installed commands pointing at the updated bundle.
• Scheduling is yours. The updater schedules nothing itself, so run it on your own cadence.³⁵
• Setup is yours. Create the stateDirectory yourself, and run --cache-warnings once to surface an unusable cache.³⁶

Progress output

Append --progress to command to drive the same update from a program that wants to show the download. Stdout is then one JSON object per line,³⁷ and every human message moves to stderr. Exit codes and the history log are the same as without it.

The binary cache

The updater never compiles harnesses from source; it passes the project cache to every update.³⁸ On a multi-user install where you are not a trusted Nix user, add the cache to your NixOS or nix-darwin configuration:³⁹

nix.settings.extra-substituters = [ "https://cache.nixos.asia/oss" ];
nix.settings.extra-trusted-public-keys = [ "oss:KO872wNJkCDgmGN3xy9dT89WAhvv13EiKncTtHDItVU=" ];

Without it, or when the cache does not yet hold the whole bundle, the update is skipped and your current version keeps working.

history.log records the skip,⁴⁰ and activation warns while the cache is unusable.

Troubleshooting

Build your own distribution

mkdir my-distribution && cd my-distribution
nix flake init -t github:juspay/agent-distro

Point my-skills at your Agent Plugins repository and edit profile.nix:

• Start from. The template includes a gateway example; agent-distro.profiles.vanilla is the reference profile shape.
• Pin. Commit flake.lock to pin your build.
• Run. Your team runs nix run github:<you>/my-distribution.
• Update. nix flake update agent-distro.

agent-distro.lib.mkFlake { profile; systems ? [ "x86_64-linux" "aarch64-linux" "aarch64-darwin" ]; cache ? …; }
# → packages.<system>: every harness, default picker, and <profile.name> bundle
#   (a bundle's bin/ carries its harness commands and `agent-distro`, its own picker)
#   apps.<system>: every harness and default picker; homeManagerModules.default;
#   lib: the same eight-name library attrset this flake exposes

agent-distro.lib.mkLaunchers { pkgs; profile; }
# → every harness launcher, plus picker and bundle (the bundle's bin/ also holds
#   that picker as `agent-distro`, defaulting to the profile)

• Outputs. mkFlake returns packages,⁴⁴ apps, homeManagerModules.default, and the same lib attrset flake.nix exposes; add other outputs with //.
• One profile. A single-profile distribution draws the narrowed list above: one profile’s rows under its description. mkFlake gives you the individual launchers and a bundle named after the profile, with the picker as its default.
• Cache. mkFlake takes an optional cache = { url; publicKey; }, defaulting to agent-distro’s cache. Push your own builds to a cache and pass it, or your users’ updates are skipped.⁴⁵

For NixOS, with your distribution bound as distro:

environment.systemPackages = [ distro.packages.${system}.my-profile ];

AI_GATEWAY=0 nix run .#omp skips gateway initialization while keeping plugins.⁴⁶

Bundle layout

A profile’s bundle (nix build .#<profile.name>) is self-describing: a consumer reads two files rather than running a command for information.

bin/<harness>…                      # one launcher per harness
bin/agent-distro                    # the picker, defaulting to this profile
share/agent-distro/profile.json     # {"description": "…", "name": "<profile.name>"}
share/agent-distro/versions         # <harness>\t<title>\t<version>, one line per harness, in menu order

profile.json comes from the same profile attributes as the picker’s --list --json, so the two cannot drift.⁴⁷

Library

Beyond the launchers, agent-distro.lib exposes the pieces Home Manager uses under the hood. Any Nix consumer, not only Home Manager, can keep a profile installed, updated, and chosen.⁴⁸

agent-distro.lib.stateDirectory { xdgStateHome; flake; profile; }
# → the string "<xdgStateHome>/agent-distro/<sha256 of {flake, profile}>", the
#   same hash Home Manager computes today. One function, so a consumer and the
#   updater can never disagree on where `current` lives.

agent-distro.lib.mkShims { pkgs; bundle; stateDirectory; }
# → a derivation whose bin/ holds one shim per bundle.commands, each
#   `exec "<stateDirectory>/current/bin/<name>"` when executable, else
#   `exec <bundle>/bin/<name>`; identical text to the Home Manager module's shims.
#   `bundle` must be a bundle from `mkLaunchers` of this agent-distro (it carries
#   `commands`); anything else is an eval error naming the problem.

agent-distro.lib.mkUpdater { pkgs; bundle; flake; profile; stateDirectory; history; nix; substituters; }
# → { config = <the generated JSON file>; command = [ node update.ts config ];
#   program = <a writeShellApplication running `command "$@"`>; }. The Home
#   Manager module's systemd ExecStart, launchd ProgramArguments (`++ ["--scheduled"]`)
#   and activation `--cache-warnings` all come from this; `command ++ [ "--progress" ]`
#   is the same update with JSON progress on stdout. `bundle` must be a
#   `mkLaunchers` bundle with a `runtime` (post-#59 ones do); the period/offset
#   come from `lib.schedule` and are not overridable here; the updater never
#   compiles, handing nix only `substituters`.

agent-distro.lib.mkPicker { pkgs; profiles; default; }
# → lib/picker.nix's derivation: the interactive profile/harness chooser, where
#   `profiles = { <name> = { profile; launchers; }; … }` — one entry per profile,
#   `launchers` the `mkLaunchers` result for it — and `default` names the preselected one.

The updater’s schedule is one lib/schedule.nix, exposed as agent-distro.lib.schedule: updateHoursUTC, defaultFrequency, updatePeriodSeconds and updateOffsetSeconds. The module, mkUpdater and any consumer read the same numbers.

Profiles

AI_PROFILE=juspay nix run github:juspay/agent-distro
AI_PROFILE=juspay AI_HARNESS=omp nix run github:juspay/agent-distro -- --version

A profile is a directory under profiles/:

profiles/
  registry.nix          # { default = "<name>"; } — the profile the list opens on
  <name>/profile.nix    # { name; description; plugins; gateway; packages; }
  <name>/npins/         # optional: the profile's pinned plugin and package sources

• Discovered. Profiles are discovered from the directory listing, so adding one is adding a directory; nothing in flake.nix names them.
• Plain data. profile.nix is a plain attrset whose name must match its directory.⁵⁰
• Pinned with npins. Each profile pins its own sources, not with flake inputs:⁵¹

let sources = import ./npins;
in { name = "example"; plugins = [ sources.skills ]; /* … */ }

• Adding a source. npins --directory profiles/<name>/npins add github <owner> <repo> follows the repository’s releases; add --branch main to follow a branch.
• Updates. The daily update advances every profile’s pins alongside the harnesses: a release pin to the latest release, a branch pin to its head.

Harnesses

Each harness is a directory under harnesses/; its README holds the design notes for that adapter.

How it works

• Profile. Harness-independent data.
• Harness. The agent application.
• Plugin. A portable Agent Plugins directory.
• Gateway. An optional LiteLLM proxy used by OMP, Pi, and OpenCode.

Harness design notes live in each directory under harnesses/.

Runtime

• TypeScript, no build step. What runs on your machine beyond the harnesses themselves⁵² is TypeScript under src/, run by Node 24’s native type stripping: no package.json, bundler or compile step.⁵³
• Dependencies. Node comes from the distribution’s nixpkgs. Its one npm dependency is yaml, for OMP’s config.⁵⁴
• Entry points. The commands you run, and the shims Home Manager installs, stay small generated shell scripts that call into it.

Reading plugins

Every plugin is read once, harness-independently, against Agent Plugins 1.0.0, by the same reader and the same harness writers.⁵⁵

• Invalid manifest. Fails the build (or the launch) with a message naming the field.
• Lesser problems. Skipped skills, disabled mcp.json files and invalid server entries are reported in the build log (or on stderr).⁵⁶
• Commands. A bare MCP command is found on PATH: the profile’s packages first, then the user’s own. A ./ command runs from the plugin.

One known gap: Claude Code expands ${VAR} in a remote server’s url and headers, which the spec forbids.⁵⁷

Shared homes

Profiles share each harness’s own home directory, so what OMP and Codex persist outlives the profile that wrote it.⁵⁸ Claude Code’s plugins last only for the session.

Development

nix build .#default    # the picker, and through it every profile's launchers
nix build .#vanilla    # one profile's bundle: its harnesses plus its own bin/agent-distro
nix flake check
just test              # offline NixOS VM tests; Linux with KVM
just test-template
just demo              # re-record doc/demo.gif and the website's stills
python3 .github/scripts/test-update-flake.py

The TypeScript’s own checks need no VM or KVM, and nix flake check at the root does not run them. Build them from the test flake:

cd test && nix build --no-link .#checks.x86_64-linux.{reader,launch-plugins,omp-adapter,pi-adapter,opencode-adapter,update-schedule,list-json,picker-layout,picker-auth}

CI

• Daily sources. CI runs .github/scripts/update-sources.sh,⁵⁹ then updates the root and test locks.
• Report. The update report reads resolved versions and each harness’s release-note metadata.
• Cache. CI pushes realised paths to the OSS cache.⁶⁰
• Merge gate. The daily update PR merges only after the required Linux/macOS builds and VM/template checks pass.⁶¹
• Cancellation. Superseded PR runs are cancelled.
• Consumers. They run nix flake update agent-distro.

For manual updates, run bash .github/scripts/update-sources.sh, nix flake update, and then bash test/update-lock.sh.

Test library

Consumers can import test/lib.nix { pkgs; launchers; profile; features; koluPlugin ? null; }. Checks are selected by required features from each harness’s metadata;⁶² picker is shared.

• Also mkLaunchers. Rebuild and gateway checks also accept mkLaunchers.
• Plugin rebuilds. Select plugin rebuild checks only for nonempty skill plugins.
• Coverage. The test flake covers vanilla (with kolu’s plugin loaded at launch), Juspay, and spec fixtures, plus registry (the picker over the whole profile registry).

Logo

doc/logo.svg is the source vector; downstream consumers (kolu) vendor a copy.

Keep it transparent, textless, readable at 16 px.

Adding a harness

Create harnesses/<name>/ with four files:

• Alongside. Pins in npins/, scripts in tests/, and an optional custom updater in update.py.
• No registration. Nothing outside this directory needs registration.⁶⁵
• Logic beyond shell. Keep it in src/harness/<name>.ts and call it with (import ../../lib/runtime.nix pkgs).script "harness/<name>.ts".⁶⁶
• Unit checks. Those that need no VM go in tests/check-adapter.ts, which receives the runtime’s src and the harness directory.
• Checks. Checks declare { name; script; requires ? []; packages ? []; env ? {}; diskSize ? null; }.⁶⁷ script is VM-driver Python.⁶⁸
• Gateway checks. They receive the shared fake service and launchers configured against it.
• Fixtures. mkLaunchers also accepts a sources = name: pkgs: … hook for package fixtures.