#agent-environments

A Nix flake library for declaring environments for coding agents (Claude Code and Codex) as modules, and for launching them under separate logins.

An environment is a set of modules: instructions (CLAUDE.md / AGENTS.md), skills, and agent settings. A launcher is a command that starts one agent in one environment, with its own state directory ~/.local/agent-environments/<id> (passed as CLAUDE_CONFIG_DIR / CODEX_HOME). Different ids mean different logins, so claude-work-acc and claude-pers-acc can share one environment but keep separate credentials.

#Use

{
  inputs.agent-environments.url = "github:<owner>/agent-environments";
  inputs.nixpkgs.follows = "agent-environments/nixpkgs";

  outputs = { agent-environments, nixpkgs, ... }:
    let
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      inherit (agent-environments.lib) mkEnvironment mkSkill mkSkillModule;
      my-skill = mkSkill {
        inherit pkgs;
        name = "my-skill";
        src = ./skills/my-skill;          # a directory containing SKILL.md
        runtimeInputs = [ pkgs.jq ];      # put on PATH for the agent
        skills = [ ];                     # other mkSkill packages it needs
      };
    in {
      packages.x86_64-linux.default = (mkEnvironment {
        inherit pkgs;
        modules = [
          (mkSkillModule my-skill)        # declares modules.skills.my-skill.enable
          {
            claude.enable = true;
            codex.enable = true;
            modules.skills.my-skill.enable = true;
            instructions.style.text = "Prefer small commits.";
            claude.settings.includeCoAuthoredBy = false;
            codex.settings.approval_policy = "on-request";
            launchers = {
              claude-work-acc.agent = "claude";
              claude-pers-acc.agent = "claude";
              codex-work-acc.agent = "codex";
            };
          }
        ];
      }).package;
    };
}

Runnable examples: examples/basic and examples/multi-account. The root flake exposes only lib and a default environment without skills: nix shell .#default puts its claude and codex launchers on PATH.

#Options

#What a launcher does

On every start, under a lock on the state dir:

1. Links the managed files into the state dir: the instruction file, one link per skill in skills/<name>, and the Codex profile. Everything it manages is listed in .agent-environments-managed.
2. Removes managed links that are no longer wanted. Anything not in the manifest (your own skills, Codex's skills/.system, logins, settings.json, config.toml) is never touched.
3. Refuses to start if a managed path is occupied by something it does not own, such as a hand-written CLAUDE.md. Move it away (or turn it into an instructions fragment) and start again.
4. Sets CLAUDE_CONFIG_DIR / CODEX_HOME, puts packages and the skills' runtime inputs on PATH, and runs the agent.

Launchers that share an id share a login and managed files. The most recent launch decides which files are linked, so only share an id between launchers of the same environment.

#Development

nix flake check          # behaviour tests (stub agents) + real Codex integration check
nix fmt -- $(git ls-files '*.nix')
nix build ./examples/basic --override-input agent-environments path:$PWD