codex - 💡(How to fix) Fix Add first-class project command environments for agent shell execution

Summary

Codex should support first-class project command environments for agent shell execution.

Today, projects that depend on a repo-local development environment have to rely on prompt instructions, shell startup behavior, or repeated command wrappers. That is fragile for agent workflows because the command runner does not have an explicit concept of "commands for this workspace should run inside this project environment."

This request is intentionally not Nix-specific. Nix is a concrete example of the problem, but the feature should be generic enough to support tools such as direnv, devenv, devbox, language version managers, containers, and other project-scoped environment providers.

Problem

Many projects intentionally keep their build tools, test runners, compilers, linters, SDKs, and environment variables out of the global user environment. Instead, the project defines a development shell or activation mechanism.

For example, a project may expect contributors to enter the environment with one of:

nix develop
direnv allow
direnv exec .
devenv shell
devbox shell

When Codex runs shell/tool commands, the model can be told in AGENTS.md to use one of those mechanisms, but that is advisory. It is easy for commands like pytest, cargo test, pnpm test, which rg, or repo scripts to run outside the intended project environment.

This shows up as missing tools, incorrect PATH, inconsistent environment variables, and confusing failures where the underlying command is fine but the command execution context is wrong.

Related issues and why this is different

Several existing issues describe concrete failures in this area. I do not think this request is a duplicate of those reports; rather, those reports are examples of symptoms that become easier to solve if Codex has an explicit project command environment abstraction.

• #4843 reports that Codex runs commands through a login shell and drops a per-project direnv/devenv environment. That issue can be fixed as a shell-regression bug, but a project command environment would give Codex a supported way to enter or materialize that environment instead of depending on inherited shell behavior.
• #16070 reports an inconsistent shell snapshot where Nix-related environment variables are preserved but Nix PATH entries are lost. That needs a direct snapshot fix, but a project command environment would also make it clearer whether command execution is supposed to inherit the parent environment, use a materialized project environment, or run outside it.
• #4210 reports PATH ordering mutation from Codex's shell invocation strategy, which breaks Nix-managed toolchains and other path-sensitive setups. Preserving PATH ordering is important regardless, but the broader design issue is that Codex does not have a first-class model for the workspace's intended tool environment.
• #4667 asked for running commands with a user-provided PATH so Nix project tools are visible. A PATH override is a useful workaround, but it is narrower than this request because many project environments set more than PATH and may require activation hooks, shell variables, SDK paths, dynamic linker paths, or long-lived services.
• #17173 asks for project-oriented agent/terminal shell selection on Windows/WSL. This request is related but cross-platform and focused on command execution environments rather than only shell selection.

In short: the existing issues are mostly about bugs in inherited shell state, shell snapshots, or platform-specific shell selection. This request is for a generic harness primitive that can address those needs more directly: "commands in this workspace run inside this declared project environment."

Desired behavior

A project or user should be able to declare the command environment for a workspace once. After that, agent shell commands should run inside that environment by default.

Conceptually:

workspace -> activate/materialize project command environment -> run agent commands there

Not:

agent command -> model remembers to rewrite it as a provider-specific wrapper

The active command environment should be visible to the agent/tooling metadata so the model can reason about where commands are being executed.

Why simple command wrapping is not enough

For example, for Nix projects it is tempting to say "just run every command as nix develop -c ...". That is useful as a fallback, but it should not be the core abstraction.

Repeated command wrapping has several problems:

• quoting and shell-composition edge cases;
• different behavior for direct exec vs shell snippets;
• repeated startup cost for heavy environments;
• unclear distinction between environment activation failures and command failures;
• noisy sandbox/approval interactions;
• reliance on the model remembering the correct wrapper every time;
• poor fit for tools that expect a persistent activated shell/session.

The user intent is not "prefix this string"; it is "this workspace's commands run in this workspace's development environment."

Possible design

Add a project-level command environment concept to Codex config.

For example:

[command_environment]
mode = "session"
provider = "generic"
enter = ["direnv", "exec", "."]

or:

[command_environment]
mode = "session"
provider = "nix"
flake = "."
shell = "default"

The exact config shape is less important than the abstraction. Useful implementation modes might include:

• session: start or enter a persistent shell/process inside the project environment and run subsequent commands there;
• env: materialize an environment snapshot once and apply it to subsequent command executions;
• wrap: provider-specific command wrapping as a fallback when session/env modes are not available.

Provider-specific helpers could exist for common tools, but a generic provider is important so users can integrate custom project environment managers without waiting for Codex-native support.

Acceptance criteria

• A workspace can declare a default command environment once.
• Agent shell commands run inside that environment by default.
• The agent does not need to remember provider-specific command prefixes.
• The active command environment is visible in command/tool metadata.
• There is an explicit per-command escape hatch to run outside the project environment.
• Environment activation/materialization failures are reported separately from failures of commands run inside the environment.
• The design supports generic providers, with Nix/direnv/devenv/devbox as examples rather than special cases only.
• Sandbox and approval behavior remains explicit and predictable.
• Repeated heavy environment startup is avoidable when a session or env-snapshot mode is available.

Example motivating case

A repo uses a Nix flake or direnv/devenv setup so project tools are available only after entering the project environment. In a regular terminal, the user can run:

direnv exec . pytest

or enter the shell once and then run:

pytest
cargo test
rg something

Codex should have a harness-level way to represent that same command execution context, rather than requiring the model to remember to wrap every individual command.

Non-goals

• This should not require making Nix the only supported environment system.
• This should not be only a PATH override.
• This should not depend solely on shell login/profile behavior.
• This should not require every command to be rewritten as nix develop -c ..., though that may be a useful fallback implementation mode.