Prefer project-local .codex as CODEX_HOME; update docs (fixes #3706)

codex-rs/README.md

@@ -21,6 +21,8 @@ The Rust implementation is now the maintained Codex CLI and serves as the defaul
 
 Codex supports a rich set of configuration options. Note that the Rust CLI uses `config.toml` instead of `config.json`. See [`docs/config.md`](../docs/config.md) for details.
 
+Project-local overrides: When running Codex inside a project that contains a `.codex/` directory at the repository root (current working directory), Codex will use that directory as `CODEX_HOME`. This means files like `config.toml`, `config.json`, `auth.json`, and history will be read from and written to the project’s `.codex/` instead of the global `~/.codex/`. If no project-local `.codex/` exists, Codex falls back to `CODEX_HOME` (when set) or `~/.codex/`.
+
 ### Model Context Protocol Support
 
 #### MCP client

codex-rs/core/src/config.rs

@@ -1226,14 +1226,23 @@ fn default_review_model() -> String {
 /// - If `CODEX_HOME` is not set, this function does not verify that the
 ///   directory exists.
 pub fn find_codex_home() -> std::io::Result<PathBuf> {
-    // Honor the `CODEX_HOME` environment variable when it is set to allow users
-    // (and tests) to override the default location.
+    // First preference: project-local ./.codex directory, if it exists.
+    // This enables per-project overrides without requiring --config or env vars.
+    let cwd = std::env::current_dir()?;
+    let project_codex = cwd.join(".codex");
+    if project_codex.is_dir() {
+        return Ok(project_codex);
+    }
+
+    // Next: honor the `CODEX_HOME` environment variable when it is set to allow
+    // users (and tests) to override the default location.
     if let Ok(val) = std::env::var("CODEX_HOME")
         && !val.is_empty()
     {
         return PathBuf::from(val).canonicalize();
     }
 
+    // Fallback: ~/.codex (do not require it to exist).
     let mut p = home_dir().ok_or_else(|| {
         std::io::Error::new(
             std::io::ErrorKind::NotFound,

docs/authentication.md

@@ -23,7 +23,11 @@ This key must, at minimum, have write access to the Responses API.
 If you've used the Codex CLI before with usage-based billing via an API key and want to switch to using your ChatGPT plan, follow these steps:
 
 1. Update the CLI and ensure `codex --version` is `0.20.0` or later
-2. Delete `~/.codex/auth.json` (on Windows: `C:\\Users\\USERNAME\\.codex\\auth.json`)
+2. Delete `$CODEX_HOME/auth.json`.
+   - `CODEX_HOME` resolution order:
+     1) Project-local `.codex/` in the current working directory, if present.
+     2) `CODEX_HOME` environment variable, if set.
+     3) Default `~/.codex/` (on Windows: `C:\\Users\\USERNAME\\.codex\\auth.json`).
 3. Run `codex login` again
 
 ## Connecting on a "Headless" Machine
@@ -32,7 +36,8 @@ Today, the login process entails running a server on `localhost:1455`. If you ar
 
 ### Authenticate locally and copy your credentials to the "headless" machine
 
-The easiest solution is likely to run through the `codex login` process on your local machine such that `localhost:1455` _is_ accessible in your web browser. When you complete the authentication process, an `auth.json` file should be available at `$CODEX_HOME/auth.json` (on Mac/Linux, `$CODEX_HOME` defaults to `~/.codex` whereas on Windows, it defaults to `%USERPROFILE%\\.codex`).
+The easiest solution is likely to run through the `codex login` process on your local machine such that `localhost:1455` _is_ accessible in your web browser. When you complete the authentication process, an `auth.json` file should be available at `$CODEX_HOME/auth.json`.
+Recall `CODEX_HOME` resolves to the project-local `.codex/` if present; otherwise to the `CODEX_HOME` env var; otherwise to the default user directory (on Mac/Linux: `~/.codex`, on Windows: `%USERPROFILE%\\.codex`).
 
 Because the `auth.json` file is not tied to a specific host, once you complete the authentication flow locally, you can copy the `$CODEX_HOME/auth.json` file to the headless machine and then `codex` should "just work" on that machine. Note to copy a file to a Docker container, you can do:
 

docs/config.md

@@ -11,7 +11,11 @@ Codex supports several mechanisms for setting config values:
   - If `value` cannot be parsed as a valid TOML value, it is treated as a string value. This means that `-c model='"o3"'` and `-c model=o3` are equivalent.
     - In the first case, the value is the TOML string `"o3"`, while in the second the value is `o3`, which is not valid TOML and therefore treated as the TOML string `"o3"`.
     - Because quotes are interpreted by one's shell, `-c key="true"` will be correctly interpreted in TOML as `key = true` (a boolean) and not `key = "true"` (a string). If for some reason you needed the string `"true"`, you would need to use `-c key='"true"'` (note the two sets of quotes).
-- The `$CODEX_HOME/config.toml` configuration file where the `CODEX_HOME` environment value defaults to `~/.codex`. (Note `CODEX_HOME` will also be where logs and other Codex-related information are stored.)
+- The `$CODEX_HOME/config.toml` configuration file. `CODEX_HOME` is resolved in this order:
+  1) A project-local `.codex/` directory in the current working directory, if present.
+  2) The `CODEX_HOME` environment variable, if set.
+  3) The default `~/.codex/` directory.
+  (Note `CODEX_HOME` will also be where logs and other Codex-related information are stored.)
 
 Both the `--config` flag and the `config.toml` file support the following options: