lux/modules/capabilities/ai/README.md

Codex installation

ai.nix installs binaries and Codex defaults on Polaris and Zenith. _sources.nix pins upstream assets; _assets.nix declares skills, MCP servers, the Ponytail marketplace and the upstream Herdr session hook. Edit instructions/codex.md for global Codex instructions.

Nix owns installation files. Codex owns writable user settings, plugin toggles, trust, credentials and sessions. Bundled/service-delivered capabilities remain vendor-managed. Update Ponytail's revision, hash and ponytailVersion together. The cache uses real directories with linked files because Codex skips symlinked plugin version directories. Do not run plugin updaters on Nix-managed assets.

Herdr's skill is linked directly from the same source as its binary. An agent can also read it with herdr --skill; no generated file is necessary. The upstream session hook supports restore, not model instruction injection.

Manual transition

Close Codex before cleaning up the previous setup and activating the new one. No migration or compatibility code runs automatically.

• Remove old standalone skills: ~/.codex/skills/ponytail, ~/.agents/skills/find-skills, ~/.agents/skills/context7-mcp.bak, and ~/.codex/skills/nixos-maintainer.bak.
• Remove the old Ponytail cache ~/.codex/plugins/cache/ponytail/ponytail. Remove any unmanaged copy at ~/.codex/plugins/cache/nix-managed/ponytail/4.9.0 if it blocks Home Manager activation. The obsolete managed ~/.codex/plugins/ponytail link is removed by Home Manager.
• In ~/.codex/config.toml, remove the old marketplaces.ponytail entry and rename plugins."ponytail@ponytail" to plugins."ponytail@nix-managed", preserving its enabled preference. Remove user launch fields for the context7, nixos and openaiDeveloperDocs MCP servers so system defaults apply; preserve toggles and unrelated preferences.
• Remove the old Herdr SessionStart command from ~/.codex/hooks.json and its ~/.codex/herdr-agent-state.sh file. Preserve unrelated hooks.
• Activate your Nix configuration, then restart Codex.

If an earlier version of this work was activated, Home Manager removes its managed instruction and integration links for other harnesses. Unmanaged copies must be removed manually if no longer wanted.