From b7afed5042ee209176ed694232aca2f73df8bcf1 Mon Sep 17 00:00:00 2001
From: Amjith Ramanujam <amjith@openai.com>
Date: Mon, 18 Aug 2025 08:00:07 -0700
Subject: [PATCH] Update README with local dev instructions.

---
 README.md          | 23 +++++++++++++++++++++++
 codex-rs/README.md | 25 ++++++++++++++++++-------
 2 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 596362a30a..61afa6328b 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@
 
 - [Quickstart](#quickstart)
   - [Installing and running Codex CLI](#installing-and-running-codex-cli)
+  - [Local Build & Run (from source)](#local-build--run-from-source)
   - [Using Codex with your ChatGPT plan](#using-codex-with-your-chatgpt-plan)
   - [Connecting on a "Headless" Machine](#connecting-on-a-headless-machine)
     - [Authenticate locally and copy your credentials to the "headless" machine](#authenticate-locally-and-copy-your-credentials-to-the-headless-machine)
@@ -95,6 +96,28 @@ Each archive contains a single entry with the platform baked into the name (e.g.
 
 </details>
 
+### Local Build & Run (from source)
+
+Build and run the Rust CLI locally from the `codex-rs` workspace.
+
+Prerequisites
+- Rust toolchain via `rustup` (toolchain pinned by `codex-rs/rust-toolchain.toml`)
+- macOS: `brew install pkg-config openssl`
+- Linux (Debian/Ubuntu): `sudo apt-get install -y build-essential pkg-config libssl-dev`
+
+Build & Run
+- Run the TUI (default):
+  ```bash
+  cd codex-rs
+  cargo run --bin codex
+  ```
+
+Convenience (via `just`, inside `codex-rs`)
+- `just codex` — run the CLI
+- `just tui` — run the TUI subcommand
+- `just fmt` — format code
+- `just fix` — apply clippy fixes
+
 ### Using Codex with your ChatGPT plan
 
 <p align="center">
diff --git a/codex-rs/README.md b/codex-rs/README.md
index b25b5cf2cc..03065bf2e8 100644
--- a/codex-rs/README.md
+++ b/codex-rs/README.md
@@ -2,16 +2,27 @@
 
 We provide Codex CLI as a standalone, native executable to ensure a zero-dependency install.
 
-## Installing Codex
+## Local Build & Run
 
-Today, the easiest way to install Codex is via `npm`, though we plan to publish Codex to other package managers soon.
+Build and run the Rust CLI locally from source.
 
-```shell
-npm i -g @openai/codex@native
-codex
-```
+Prerequisites
+- Rust toolchain via `rustup` (toolchain pinned by `rust-toolchain.toml`)
+- macOS: `brew install pkg-config openssl`
+- Linux (Debian/Ubuntu): `sudo apt-get install -y build-essential pkg-config libssl-dev`
 
-You can also download a platform-specific release directly from our [GitHub Releases](https://github.com/openai/codex/releases).
+Build & Run
+- Run the TUI (default):
+  ```bash
+  cd codex-rs
+  cargo run --bin codex
+  ```
+
+Convenience (via `just`, inside `codex-rs`)
+- `just codex` — run the CLI
+- `just tui` — run the TUI subcommand
+- `just fmt` — format code
+- `just fix` — apply clippy fixes
 
 ## What's new in the Rust CLI