# Clone the repository and navigate to the CLI package
git clone https://github.com/openai/codex.git
cd codex/codex-cli
# Install dependencies and build
npm install
npm run build
# Run the locally‑built CLI directly
node ./dist/cli.js --help
# Or link the command globally for convenience
npm link
```
</details>
---
## Configuration
Codex looks for config files in **`~/.codex/`**.
```yaml
# ~/.codex/config.yaml
model: o4-mini # Default model
fullAutoErrorMode: ask-user # or ignore-and-continue
```
You can also define custom instructions:
```yaml
# ~/.codex/instructions.md
- Always respond with emojis
- Only use git commands if I explicitly mention you should
```
---
## FAQ
<details>
<summary>How do I stop Codex from touching my repo?</summary>
Codex always runs in a **sandbox first**. If a proposed command or file change looks suspicious you can simply answer **n** when prompted and nothing happens to your working tree.
</details>
<details>
<summary>Does it work on Windows?</summary>
Not directly, it requires [Linux on Windows (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/install) – Codex is tested on macOS and Linux with Node≥22.
Any model available with [Responses API](https://platform.openai.com/docs/api-reference/responses). The default is `o4-mini`, but pass `--model gpt-4o` or set `model: gpt-4o` in your config file to override.
More broadly We welcome contributions – whether you are opening your very first pull request or you’re a seasoned maintainer. At the same time we care about reliability and long‑term maintainability, so the bar for merging code is intentionally **high**. The guidelines below spell out what “high‑quality” means in practice and should make the whole process transparent and friendly.
### Development workflow
- Create a _topic branch_ from `main`– e.g. `feat/interactive-prompt`.
- Keep your changes focused. Multiple unrelated fixes should be opened as separate PRs.
- Use `npm run test:watch` during development for super‑fast feedback.
- We use **Vitest** for unit tests, **ESLint** + **Prettier** for style, and **TypeScript** for type‑checking.
- Make sure all your commits are signed off with `git commit -s ...`, see [Developer Certificate of Origin (DCO)](#developer-certificate-of-origin-dco) for more details.
```bash
#Watch mode (tests rerun on change)
npm run test:watch
#Type‑check without emitting files
npm run typecheck
#Automatically fix lint + prettier issues
npm run lint:fix
npm run format:fix
```
### Writing high‑impact code changes
1.**Start with an issue.**
Open a new one or comment on an existing discussion so we can agree on the solution before code is written.
2.**Add or update tests.**
Every new feature or bug‑fix should come with test coverage that fails before your change and passes afterwards. 100% coverage is not required, but aim for meaningful assertions.
3.**Document behaviour.**
If your change affects user‑facing behaviour, update the README, inline help (`codex --help`), or relevant example projects.
4.**Keep commits atomic.**
Each commit should compile and the tests should pass. This makes reviews and potential rollbacks easier.
### Opening a pull request
- Fill in the PR template (or include similar information) –**What? Why? How?**
- Run **all** checks locally (`npm test && npm run lint && npm run typecheck`).
CI failures that could have been caught locally slow down the process.
- Make sure your branch is up‑to‑date with `main` and that you have resolved merge conflicts.
- Mark the PR as **Ready for review** only when you believe it is in a merge‑able state.
### Review process
1. One maintainer will be assigned as a primary reviewer.
2. We may ask for changes – please do not take this personally. We value the work, we just also value consistency and long‑term maintainability.
3. When there is consensus that the PR meets the bar, a maintainer will squash‑and‑merge.
### Community values
- **Be kind and inclusive.** Treat others with respect; we follow the [Contributor Covenant](https://www.contributor-covenant.org/).
- **Assume good intent.** Written communication is hard – err on the side of generosity.
- **Teach & learn.** If you spot something confusing, open an issue or PR with improvements.
### Getting help
If you run into problems setting up the project, would like feedback on an idea, or just want to say _hi_– please open a Discussion or jump into the relevant issue. We are happy to help.
Together we can make Codex CLI an incredible tool. **Happy hacking!** :rocket:
### Developer Certificate of Origin (DCO)
All commits **must** include a `Signed‑off‑by:` footer.
This one‑line self‑certification tells us you wrote the code and can contribute it under the repo’s license.
#### How to sign (recommended flow)
```bash
# squash your work into ONE signed commit
git reset --soft origin/main # stage all changes
git commit -s -m "Your concise message"
git push --force-with-lease # updates the PR
```
> We enforce **squash‑and‑merge only**, so a single signed commit is enough for the whole PR.
