close: #651
Hi! @tibo-openai 👋 Could you share some great examples of
`instructions.md` files? Thanks!
---------
Co-authored-by: Thibault Sottiaux <tibo@openai.com>
When using a non-built-in provider with the `--provider` option, users
are prompted:
```
Set the environment variable <provider>_API_KEY and re-run this command.
You can create a <provider>_API_KEY in the <provider> dashboard.
```
However, many users are confused because, even after correctly setting
`<provider>_API_KEY`, authentication may still fail unless
`OPENAI_API_KEY` is _also_ present in the environment. This is not
intuitive and leads to ambiguity about which API key is actually
required and used as a fallback, especially when using custom or
third-party (non-listed) providers.
Furthermore, the original README/documentation did not mention the
requirement to set `<provider>_BASE_URL` for non-built-in providers,
which is necessary for proper client behavior. This omission made the
configuration process more difficult for users trying to integrate with
custom endpoints.
This introduces a Python script (written by Codex!) to verify that the
table of contents in the root `README.md` matches the headings. Like
`scripts/asciicheck.py` in https://github.com/openai/codex/pull/513, it
reports differences by default (and exits non-zero if there are any) and
also has a `--fix` option to synchronize the ToC with the headings.
This will be enforced by CI and the changes to `README.md` in this PR
were generated by the script, so you can see that our ToC was missing
some entries prior to this PR.
This all started because I was going to write a script to autogenerate
the Table of Contents in the root `README.md`, but I noticed that the
`href` for the "Why Codex?" heading was `#whycodex` instead of
`#why-codex`. This piqued my curiosity and it turned out that the space
in "Why Codex?" was not an ASCII space but **U+00A0**, a non-breaking
space, and so GitHub ignored it when generating the `href` for the
heading.
This also meant that when I did a text search for `why codex` in the
`README.md` in VS Code, the "Why Codex" heading did not match because of
the presence of **U+00A0**.
In short, these types of Unicode characters seem like a hazard, so I
decided to introduce this script to flag them, and if desired, to
replace them with "good enough" ASCII equivalents. For now, this only
applies to the root `README.md` file, but I think we should ultimately
apply this across our source code, as well, as we seem to have quite a
lot of non-ASCII Unicode and it's probably going to cause `rg` to miss
things.
Contributions of this PR:
* `./scripts/asciicheck.py`, which takes a list of filepaths and returns
non-zero if any of them contain non-ASCII characters. (Currently, there
is one exception for ✨ aka **U+2728**, though I would like to default to
an empty allowlist and then require all exceptions to be specified as
flags.)
* A `--fix` option that will attempt to rewrite files with violations
using a equivalents from a hardcoded substitution list.
* An update to `ci.yml` to verify `./scripts/asciicheck.py README.md`
succeeds.
* A cleanup of `README.md` using the `--fix` option as well as some
editorial decisions on my part.
* I tried to update the `href`s in the Table of Contents to reflect the
changes in the heading titles. (TIL that if a heading has a character
like `&` surrounded by spaces, it becomes `--` in the generated `href`.)
Reverts https://github.com/openai/codex/pull/386 because:
* The parsing logic for shell commands was unsafe (`split(/\s+/)`
instead of something like `shell-quote`)
* We have a different plan for supporting auto-approved commands.
This PR implements support for reading the approvalMode setting from the
user's config file (`~/.codex/config.json` or `~/.codex/config.yaml`),
allowing users to set a persistent default approval mode without needing
to specify command-line flags for each session.
Changes:
- Added approvalMode to the AppConfig type in config.ts
- Updated loadConfig() to read the approval mode from the config file
- Modified saveConfig() to persist the approval mode setting
- Updated CLI logic to respect the config-defined approval mode (while
maintaining CLI flag priority)
- Added comprehensive tests for approval mode config functionality
- Updated README to document the new config option in both YAML and JSON
formats
- additions to `.gitignore` for other CLI tools
Motivation:
As a user who regularly works with CLI-tools, I found it odd to have to
alias this with the command flags I wanted when `approvalMode` simply
wasn't being parsed even though it was an optional prop in `config.ts`.
This change allows me (and other users) to set the preference once in
the config file, streamlining daily usage while maintaining the ability
to override via command-line flags when needed.
Testing:
I've added a new test case loads and saves approvalMode correctly that
verifies:
- Reading the approvalMode from the config file works correctly
- Saving the approvalMode to the config file works as expected
- The value persists through load/save operations
All tests related to the implementation are passing.
This pull request adds a feature that allows users to configure
auto-approved commands via a `safeCommands` array in the configuration
file.
## Related Issue
#380
## Changes
- Added loading and validation of the `safeCommands` array in
`src/utils/config.ts`
- Implemented auto-approval logic for commands matching `safeCommands`
prefixes in `src/approvals.ts`
- Added test cases in `src/tests/approvals.test.ts` to verify
`safeCommands` behavior
- Updated documentation with examples and explanations of the
configuration
Since we migrated to `pnpm` in #287, this updates the README to reflect
that change.
Just a small cleanup to align the commands with the current setup.
This PR introduces a Nix flake configuration to enable reproducible
development environments:
- Adds flake.nix defining a devShell with necessary dependencies.
- Updates README.md with usage instructions for `nix develop`.
- Ensures CI compatibility with Nix for consistent builds.
This PR adds a shell wrapper in `codex-cli/bin/codex` to detect node or
bun as the runtime.
It updates:
- `package.json` bin entry
- published files list to include bin/
- README install instructions to include `bun install -g @openai/codex`
Add a note in Quickstart that you can drop your API key into a `.env`
file
(since dotenv support was introduced in 40266be#122).
✅ Ran `npm test && npm run lint && npm run typecheck` locally
I have read the CLA Document and I hereby sign the CLA
Signed-off-by: Dan Lewis <dglewi@gmail.com>
**What**?
Add a `Tracing / Verbose Logging` section to the README
**Why**?
Enable easier troubleshooting by logging full API requests, responses,
and prompt details used during code generation.
**How**?
Inserted the new section between `Non‑interactive / CI mode` and `FAQ`.
# Add Husky and lint-staged for automated code quality checks
## Description
This PR adds Husky Git hooks and lint-staged to automate code quality
checks during the development workflow.
## Features Added
- Pre-commit hook that runs lint-staged to check files before committing
- Pre-push hook that runs tests and type checking before pushing
- Configuration for lint-staged to format and lint different file types
- Documentation explaining the Husky setup and usage
- Updated README.md with information about Git hooks
## Benefits
- Ensures consistent code style across the project
- Prevents pushing code with failing tests or type errors
- Reduces the need for style-related code review comments
- Improves overall code quality
## Implementation Details
- Added Husky and lint-staged as dev dependencies
- Created pre-commit and pre-push hooks
- Added configuration for lint-staged
- Added documentation in HUSKY.md
- Updated README.md with a new section on Git hooks
## Testing
The hooks have been tested locally and work as expected:
- Pre-commit hook runs ESLint and Prettier on staged files
- Pre-push hook runs tests and type checking
I have read the CLA Document and I hereby sign the CLA
---------
Signed-off-by: Alpha Diop <alphakhoss@gmail.com>
**What?**
Add a section to the README documenting the current limitation for Codex
with Zero Data Retention (ZDR) organizations.
**Why?**
Users from ZDR organizations encounter errors due to the Responses API’s
requirement for `store:true`, which is incompatible with ZDR policies.
See #106 for more info.
**How?**
- Added a new section in the README, after FAQ and before Funding.
- Explained the error message and reason.
- Linked to documentation as linked in the issue.
Separated the `node ./dist/cli.js --help ` and `node ./dist/cli.js `.
The comment suggested `node ./dist/cli.js --help ` was to run the
locally-built CLI but in fact it shows the usage an options. It is a
minor change and clarifies the flow for new developers.
Why
---
Improves the usability of the `codex` CLI by adding shell completion for
file paths. This allows users to quickly complete file arguments using
tab completion in bash, zsh, and fish shells. Enable via `eval "$(codex
completion <shell>)"`.
One of my favorite use cases is a read-only one; have `codex` suggest areas of the codebase that need attention. From here, it's also easy for the user to select one of the proposed tasks and have `codex` make the PR.
