Local project .codex directory support

Agreed, I would find project-specific prompts especially useful.

This feature is critical to me and my workflow. Codex is entirely useless for me without it. Here is a little demo with the feature built in. If someone wants to improve on what I've done, then merge it in.
https://github.com/Fomo-Driven-Development/claude-codex

Coming from claude code I'm surprised this isn't implemented. While I found sub-agents nearly useless (despite trying hard to make them useful) I find project level custom slash commands pretty core to my workflows (i had 10+ i regularly used in claude code)

Same. This is basically necessary for all nix projects that have non-trivial toolchains that must be available for the mcp.

This is related to #2554.

per-repo mcp servers and /prompts are used heavily in very large enterprise repos. Experience from GitHub copilot says I need this capability to keep hundreds of engineers working on a repo on the right work flow.

It becomes hard to manage codex prompts, config, skills from a single global location. Please add local .codex folder support.

I made a feature-request that was rightly closed to consolidate things. Sharing the details here to further the discussion:
...
.codex/prompts/ Works exactly as currently supported. This is just a namespaced, repo-local location.

.codex/rules/ Equivalent to Cursor Rules, so file-based rules that are activated via glob patterns and are contextual and scoped. This lets Codex apply guidance where relevant, without polluting global context.

.codex/skills/ Instead of requiring one folder per skill, allow both files and folders. This keeps simple skills in a single file, while more complex ones can include specific data, files, or examples relevant to the skill.

.codex/skills/
  design-feature.md
  ci/
    README.md
    examples/
    skill.md

.codex/docs/ This is a lightweight alternative to docs-focused MCPs. There are two possible ways to support it: either a folder of relevant documentation files (e.g., the complete Convex rules file) or a single file that links to documentation pages and includes descriptions, hints, and usage context (like skills and prompts do right now).

Option 1 could go even further by including a description file (like Option 2), but using local files instead of web search. Both options would let Codex decide which docs to consult and load them selectively, based on descriptions or glob-based activation (similar to Cursor rules). This would simplify documentation grounding without needing external tools.

It would great if there was just one location for all these like the AGENTS.md standard:

• Github it is .github/prompts/*.md
• https://code.visualstudio.com/docs/copilot/customization/prompt-files
• Claude code it is .claude/commands/*.md
• https://code.claude.com/docs/en/slash-commands#project-commands
• This suggestion would be .codex/**/*.md

I really wish a standard emerges that all these plugins supported like .prompts/**/*.md

You can now add skills to projects. Codex will pick up .codex folders nested in a git repo.

https://x.com/embirico/status/2002126655133987009

Skills should have a manual_only metadata flag. It would remove the need for a command/prompts folder completely. When true the skill is excluded from the agent's skill list preventing unintended use, but still present in the skill search provided by $ and remains invocable of course ($skill-name). When $$ is entered, the skill list should be filtered to only those that are manually invocable.

This now works for $REPO_ROOT/.codex/skills and the documentation is updated. Thanks @embirico and team!

I've started to invest in Codex Rules to improve the development experience for working in my repo. It would be awesome to be able to commit these rules along side my skills.

I’m working with Codex across multiple repositories and have encountered real usability pain due to the current handling of the .codex directory.

Right now, unless CODEX_HOME is explicitly exported, Codex always defaults to $HOME/.codex, even when there is a .codex folder present in the project. This forces me to manually update environment variables for each project, and when switching contexts I often need to re‑login or reset auth context, which interrupts workflows.

I’ve implemented a shell wrapper to approximate a more useful behavior (in your .bashrc):

codex() {
  local dir="$PWD"
  local used_path=""
  local GREEN="\033[0;32m"
  local YELLOW="\033[0;33m"
  local CYAN="\033[0;36m"
  local RESET="\033[0m"

  while [[ "$dir" != "/" ]]; do
    if [[ -d "$dir/.codex" ]]; then
      used_path="$dir/.codex"
      echo -e "${CYAN}[codex]${RESET} Using project-local .codex at ${GREEN}$used_path${RESET} (.bashrc)"
      export CODEX_HOME="$used_path"
      command codex "$@"
      return
    fi
    dir="$(dirname "$dir")"
  done

  used_path="$HOME/.codex"
  echo -e "${YELLOW}[codex]${RESET} Using global .codex at ${GREEN}$used_path${RESET} (.bashrc)"
  export CODEX_HOME="$used_path"
  command codex "$@"
}

This works, but it’s a workaround: the underlying client should natively detect .codex in the current project and prefer it automatically. It also has the annoying side effect of requiring a re-login

Ideally, Codex should support a hierarchical resolution where:

• it checks for a .codex directory in the current working directory or project root
• if not found, it checks parent directories
• if still not found, it falls back to $HOME/.codex

This behavior is common in many developer tools and would significantly improve multi‑project workflows.

Relevant related discussions:

• Local project .codex directory support #3706
• .codex per project duplicate #3839
• Custom prompts in local .codex #4734

Adding in a request to support project-level allow/deny tool calls. I’d like to configure our project to pre-allow safe calls for common shell, git and gh commands, to the benefit of every developer and worktrees. Claude Code allows this in a .claude/settings.json with allow / deny keys, and it’s rather useful.

This should now work if you're using the Codex CLI. You can define a project-local .codex/config.toml file and specify project-specific settings like MCP servers. One caveat: project-local config.toml files are ignored if the project is not trusted.

We're still working on plumbing this feature through for the Codex IDE Extension. I'll keep this thread open until that's complete.

We don't plan to add support for project-local custom prompts because we are going to deprecate that feature. We recommend using the newer "skills" feature which provides a superset of the custom prompt functionality. Project-local skills are already supported.

We don't plan to add support for project-local custom prompts because we are going to deprecate that feature.

Are you planning to deprecate global prompts support as well?
I mean wouldn't it be inconsistent if project-local configs gonna work with skills and config.toml, but not with prompts?

Are you planning to deprecate global prompts support as well?

Yes, that's the plan.

This will be included in the next release of the IDE Extension! As I mentioned above, it has been implemented in the CLI for the past few releases.