#agent-environments — design

Status: self-authored during an autonomous run (user asked to work autonomously and consult Codex). Reviewed by Codex (review-1: blocking points folded in), not yet by the user.

#Goal

A Nix flake library for declaring reproducible configurations ("environments") for coding agents — Claude Code and Codex for now — and launching them under separate identities (logins). Other flakes consume it; examples/ shows how.

#Requirements (from the user)

• Module-based: modules add text to the instruction file (AGENTS.md / CLAUDE.md) and enable skills, e.g. modules.skills.xyz.enable = true.
• Several launchers such as claude-work-acc, claude-pers-acc. They may share one environment but log in separately. Each launcher gets its own state directory ~/.local/agent-environments/<id>, passed in with CLAUDE_CONFIG_DIR / CODEX_HOME.
• Each environment is its own set of modules.
• Skills are packaged. A skill can need runtime tools and other skills.
• Flakes. claude-code and codex come in as inputs: github:sadjow/claude-code-nix, github:sadjow/codex-cli-nix.
• Standalone only (no home-manager). The root flake exposes the library plus one default environment with no skills.

#Architecture

flake.nix                  inputs: nixpkgs, claude-code, codex
lib/default.nix            mkEnvironment, mkSkill, mkSkillModule
modules/core.nix           instructions, skills, launchers, assertions
modules/claude.nix         claude.{enable,package,settings}
modules/codex.nix          codex.{enable,package,settings}
modules/launcher.nix       wrapper script generation
checks/                    behaviour tests (stub agents, temp HOME)
examples/<name>/flake.nix  consumer flakes

#Evaluation

lib.mkEnvironment { pkgs, modules ? [] } runs lib.evalModules over the core modules plus the user's modules, with pkgs passed as a module argument. It returns the evaluated config along with package (a symlinkJoin of every launcher) and launchers (an attrset of per-launcher packages).

The flake's lib is system-independent. mkEnvironment receives pkgs, and the flake sets default agent packages for pkgs.stdenv.hostPlatform.system from its own inputs. Consumers can override those with claude.package / codex.package.

#Core options

• instructions.<name> = { text : lines; order : int = 1000; } — fragments sorted by (order, name) and joined with a blank line into one document. That document becomes CLAUDE.md for Claude and AGENTS.md for Codex. Modules add a fragment by defining an entry.
• skills.packages : listOf package — skill derivations made by mkSkill. The effective set is the transitive closure over passthru.skillDeps, deduplicated by skill name. Two different derivations with the same name → evaluation error.
• claude.enable, claude.package, claude.settings : attrs (JSON).
• codex.enable, codex.package, codex.settings : attrs (TOML).
• launchers.<name> = { agent : enum ["claude" "codex"]; id : str = <name>; stateDir : str = "~/.local/agent-environments/${id}"; }. The name is the command name. stateDir must be absolute or start with ~/ (assertion); it is shell-quoted as a literal, and only the leading ~/ becomes $HOME. A launcher's agent must be enabled (assertion). id and launcher names must match ^[A-Za-z0-9][A-Za-z0-9._-]*$ (assertion).
• Launchers are always declared explicitly. There are no implicit default launchers, because attrset options merge by key and a hidden default could not be dropped cleanly.

#Modules namespace

modules.* is where optional features live, e.g. modules.skills.<name>.enable. The helper lib.mkSkillModule skill produces a module declaring options.modules.skills.<skill.skillName>.enable and, when it is enabled, adding the skill to skills.packages. Options cannot be generated from config (that would recurse infinitely), so consumers import one module per skill they want to make available. Instruction modules are plain modules that define instructions.<name>.

#Skill packaging

lib.mkSkill { pkgs, name, src, runtimeInputs ? [], skills ? [] }:

• name must match ^[A-Za-z0-9][A-Za-z0-9._-]*$ (evaluation-time check).
• Output: $out/ is the skill directory (it must contain SKILL.md; checked at build time). The same directory works for both agents, since Claude Code and Codex share the SKILL.md format.
• passthru = { skillName = name; runtimeInputs; skillDeps = skills; }.
• Runtime inputs: the launcher puts the union of all effective skills' runtimeInputs on PATH (prepended). Skills run inside the agent's shell, so this is the smallest mechanism that works for both agents.

#Launcher (runtime)

The wrapper is a writeShellApplication per launcher. Everything it manages is listed in a manifest, $state/.agent-environments-managed (one relative path per line). On every start it:

1. mkdir -p "$state/skills", then takes flock on $state/.agent-environments.lock for the setup phase only; the lock fd is closed before exec.
2. Computes the wanted set of managed links: the instruction file (CLAUDE.md for claude, AGENTS.md for codex, when there are instructions), skills/<name> for each effective skill, and the codex profile TOML (when there are settings).
3. Removes every path in the old manifest that is not wanted any more, but only when it is still a symlink. Anything else is left in place.
4. For each wanted path that exists: unless it is listed in the old manifest and is still a symlink, stop with an error naming the path (user data, including user symlinks, is never replaced and there are no automatic backups). Otherwise replace it atomically (ln -s to a temp name, then mv -T).
5. Writes the new manifest atomically. Codex's own skills/.system and any user-installed skills are never touched, because they are not in the manifest.
6. Settings, layered so the agents stay free to write their own files:
   • Claude: --settings <store settings.json> when claude.settings != {}. settings.json, .claude.json and .credentials.json in the state dir stay owned by Claude.
   • Codex: $state/agent-environments.config.toml (a managed link to the store TOML) plus --profile agent-environments, which layers $CODEX_HOME/<profile>.config.toml over config.toml. config.toml (which holds trust entries) and auth.json stay owned by Codex. Skipped when codex.settings == {}.
7. export CLAUDE_CONFIG_DIR="$state" / export CODEX_HOME="$state", prepend the runtime inputs to PATH, then exec <agent> <managed flags> "$@".

Logins are therefore per launcher: claude-work-acc and claude-pers-acc have different ids, so different state dirs, so different credentials, even when they come from the same environment. Two launchers that should share a login can set the same id. They then also share managed content: the last launch wins, so they should come from the same environment. This is documented, not enforced.

#Root flake outputs

• lib — mkEnvironment, mkSkill, mkSkillModule.
• packages.<system>.default — the default environment: claude + codex enabled, launchers claude and codex with ids default-claude / default-codex, no skills and no instructions.
• checks.<system>.* — behaviour tests.
• formatter — nixfmt.

#Examples

• examples/basic — one environment, one instruction fragment, one local skill with a runtime dependency and a skill dependency.
• examples/multi-account — one module set, launchers claude-work-acc, claude-pers-acc, codex-work-acc, plus a second environment with a different module set.

Each example is a flake with inputs.agent-environments.url = "path:../..";.

#Error handling

• Evaluation-time assertions: a launcher's agent is disabled; an unsafe id, launcher or skill name; conflicting skill names. A skill without SKILL.md fails at build time.
• Runtime: never delete non-symlink files and never replace unmanaged ones; fail loudly (set -euo pipefail) and say which path conflicts.

#Testing

nix flake check runs derivation checks that execute the launchers with stub claude/codex packages (scripts that dump argv, env and state-dir contents), using a temporary HOME:

• the state dir is created under $HOME/.local/agent-environments/<id> and the right env var points at it;
• two launchers from one environment get different state dirs (separate logins);
• the instruction file carries the fragments in order;
• dependency skills are linked transitively; a skill's runtime tool is on PATH;
• a skill that is no longer enabled is unlinked on the next launch, while user skill dirs, user symlinks and .system are kept;
• a pre-existing user CLAUDE.md makes the launcher fail and is left untouched;
• the --settings / --profile flags appear only when settings are non-empty.

One integration check runs the real Codex package offline to confirm that it discovers $CODEX_HOME/AGENTS.md, the skills and the profile, if Codex has a non-interactive way to show this. If it does not, that is recorded as a coverage gap and checked by hand.

Examples are built with nix build ./examples/<x> --override-input agent-environments path:$PWD.

#Out of scope (YAGNI)

home-manager integration, MCP server modules, plugins, per-project config, agents other than Claude Code and Codex.