~ruther/agent-environments

ref: 81614f914cf4a4cf9f280289e7ec7925d0e8e591 agent-environments/TODOs.md -rw-r--r-- 4.5 KiB
81614f91 — František Boháček Add claude.plugins: plugin directories loaded with --plugin-dir 2 months ago

#TODOs — agent-environments

Self-authored tracker, not approved by the user (the user said: "Work autonomously, consult with codex, create a todo for yourself and follow it").

#Goal

A Nix flake library for module-based Claude Code / Codex environments with per-launcher logins and packaged skills. Spec: docs/superpowers/specs/2026-09-26-agent-environments-design.md.

#Scope and authority

  • In scope: this repo only (/home/fbw/src/agent-environments), local commits on main.
  • Not authorized: pushing, creating remotes, touching ~/.claude, ~/.codex or ~/.local/agent-environments for real (tests use a temp HOME).
  • Network: GitHub + cache.nixos.org for flake inputs only.
  • Companion: ~/.nix-profile/bin/codex exec --sandbox read-only (unsandboxed).
  • Evidence dir: /tmp/claude-1001/agent-environments/.

#Success criteria

  1. nix flake check passes, and its checks cover every behaviour listed in the spec's Testing section.
  2. nix build .#default gives bin/claude and bin/codex.
  3. Both examples build against the local checkout (--override-input agent-environments path:$PWD).
  4. Codex has reviewed the implementation and has no blocking findings left.

#Tasks

  • [x] Preflight (see the log below)
  • [x] Design spec plus a Codex review of it (review-1: 6 blocking points, all folded in)
  • [x] T1 flake.nix skeleton + lock (nixpkgs, claude-code, codex)
  • [x] T2 lib: mkEnvironment, mkSkill, mkSkillModule
  • [x] T3 modules: core (instructions, skills closure, launchers, assertions), claude, codex
  • [x] T4 launcher script (manifest, flock, atomic links, settings layering)
  • [x] T5 checks with stub agents (all spec behaviours)
  • [x] T6 real-codex integration probe (or record coverage gap)
  • [x] T7 default package + formatter
  • [x] T8 examples/basic, examples/multi-account; build both
  • [x] T9 README
  • [x] T10 Codex review of the implementation; fix blocking findings
  • [x] T11 Final verification + summary

#Log

  • Preflight: nix 2.34.8 OK; codex companion at ~/.nix-profile/bin/codex (0.155.1) answered a probe; git init -b main done; GitHub reachable with allowed_domains; inputs resolve: claude-code-nix (claude-code 2.1.283), codex-cli-nix (codex 0.157.1).
  • Facts: claude --settings <file> layers settings; codex --profile <n> layers $CODEX_HOME/<n>.config.toml; the codex binary refers to CODEX_HOME/skills and a skills/.system directory.
  • Decisions after review-1: explicit launchers only; manifest-based ownership; flock + atomic mv -T; name validation; no backups (fail on conflict); shared ids are documented, not enforced.
  • T1–T4 (c42fffc): the flake builds; the default package gives bin/claude + bin/codex. Nix commands run unsandboxed: the Bash sandbox bind-mounts char devices (.gitmodules, .bashrc, …) into the repo, which breaks Nix's git/path fetchers.
  • T5 (83a1cdd): 7 checks. Mutation tests: dropping the PATH export → launch-contract FAIL; dropping the "still a symlink" condition → refuses-unmanaged FAIL (after switching that case to a regular file, because mv -T fails on non-empty directories anyway).
  • T6 (b61dc9a): real Codex 0.157.1 debug prompt-input through the launcher shows the AGENTS.md, skill and profile markers, run inside the Nix sandbox. COVERAGE GAP: there is no offline equivalent for Claude (it needs a login). Claude reading $CLAUDE_CONFIG_DIR/CLAUDE.md and symlinked skills/<name> rests on the docs (cited in review-1) plus home-manager's claude-code module using the same store-symlink layout. Not run here.
  • T7–T9 (90e573d, db15f3d): nixfmt; both examples build with --override-input; a smoke run of claude-basic/codex-basic --version in a temp HOME links both skills (the dependency closure) and CLAUDE.md.
  • T10: review rounds, cap 10 (skill default; the user did not set one). Round 1 (pkg 5017493): 3 findings. [Major] lock/temp paths wrote through symlinks → fixup 40a460a/af62e81; [Major] symlinked skills dir → same fixups; [Minor] README nix run → fixup 5c05d4d. Round 2 (pkg 5c05d4d): 1 finding. [Major] stateDir evaluated as shell code → literal path (absolute or ~/), fixups 0294b46/a8e9e2e/ef05cec/9c5c1a3. Round 3 (pkg 9c5c1a3): NO REQUESTED CHANGES → approved at round 3 of 10.
  • T11 at 9c5c1a3: nix flake check exit 0 (10 checks, x86_64-linux only); .#default → bin/claude, bin/codex; both examples build. Not verified: aarch64/darwin builds; real Claude loading CLAUDE.md/skills (see T6); the fixup commits are unsquashed (the user's rule).