valknar/llmx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 5: Configuration & Documentation

Browse Source 
Updated all documentation and configuration files:

Documentation changes:
- Updated README.md to describe LLMX as LiteLLM-powered fork
- Updated CLAUDE.md with LiteLLM integration details
- Updated 50+ markdown files across docs/, llmx-rs/, llmx-cli/, sdk/
- Changed all references: codex → llmx, Codex → LLMX
- Updated package references: @openai/codex → @llmx/llmx
- Updated repository URLs: github.com/openai/codex → github.com/valknar/llmx

Configuration changes:
- Updated .github/dependabot.yaml
- Updated .github workflow files
- Updated cliff.toml (changelog configuration)
- Updated Cargo.toml comments

Key branding updates:
- Project description: "coding agent from OpenAI" → "coding agent powered by LiteLLM"
- Added attribution to original OpenAI Codex project
- Documented LiteLLM integration benefits

Files changed: 51 files (559 insertions, 559 deletions)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Sebastian Krüger
2025-11-11 14:45:40 +01:00
parent 0c2c36e14e
commit c493ea1347
51 changed files with 559 additions and 559 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
llmx-cli/README.md
View File

@@ -1,12 +1,12 @@
<h1 align="center">OpenAI Codex CLI</h1>
<h1 align="center">OpenAI LLMX CLI</h1>
<p align="center">Lightweight coding agent that runs in your terminal</p>
<p align="center"><code>npm i -g @openai/codex</code></p>
<p align="center"><code>npm i -g @llmx/llmx</code></p>
> [!IMPORTANT]
> This is the documentation for the _legacy_ TypeScript implementation of the Codex CLI. It has been superseded by the _Rust_ implementation. See the [README in the root of the Codex repository](https://github.com/openai/codex/blob/main/README.md) for details.
> This is the documentation for the _legacy_ TypeScript implementation of the LLMX CLI. It has been superseded by the _Rust_ implementation. See the [README in the root of the LLMX repository](https://github.com/valknar/llmx/blob/main/README.md) for details.
![Codex demo GIF using: codex "explain this codebase to me"](../.github/demo.gif)
![LLMX demo GIF using: llmx "explain this codebase to me"](../.github/demo.gif)
---
@@ -17,7 +17,7 @@
- [Experimental technology disclaimer](#experimental-technology-disclaimer)
- [Quickstart](#quickstart)
- [Why Codex?](#why-codex)
- [Why LLMX?](#why-llmx)
- [Security model & permissions](#security-model--permissions)
- [Platform sandboxing details](#platform-sandboxing-details)
- [System requirements](#system-requirements)
@@ -37,7 +37,7 @@
- [Environment variables setup](#environment-variables-setup)
- [FAQ](#faq)
- [Zero data retention (ZDR) usage](#zero-data-retention-zdr-usage)
- [Codex open source fund](#codex-open-source-fund)
- [LLMX open source fund](#llmx-open-source-fund)
- [Contributing](#contributing)
- [Development workflow](#development-workflow)
- [Git hooks with Husky](#git-hooks-with-husky)
@@ -49,7 +49,7 @@
- [Getting help](#getting-help)
- [Contributor license agreement (CLA)](#contributor-license-agreement-cla)
- [Quick fixes](#quick-fixes)
- [Releasing `codex`](#releasing-codex)
- [Releasing `llmx`](#releasing-llmx)
- [Alternative build options](#alternative-build-options)
- [Nix flake development](#nix-flake-development)
- [Security & responsible AI](#security--responsible-ai)
@@ -63,7 +63,7 @@
## Experimental technology disclaimer
Codex CLI is an experimental project under active development. It is not yet stable, may contain bugs, incomplete features, or undergo breaking changes. We're building it in the open with the community and welcome:
LLMX CLI is an experimental project under active development. It is not yet stable, may contain bugs, incomplete features, or undergo breaking changes. We're building it in the open with the community and welcome:
- Bug reports
- Feature requests
@@ -77,7 +77,7 @@ Help us improve by filing issues or submitting PRs (see the section below for ho
Install globally:
```shell
npm install -g @openai/codex
npm install -g @llmx/llmx
```
Next, set your OpenAI API key as an environment variable:
@@ -97,7 +97,7 @@ export OPENAI_API_KEY="your-api-key-here"
<details>
<summary><strong>Use <code>--provider</code> to use other models</strong></summary>
> Codex also allows you to use other providers that support the OpenAI Chat Completions API. You can set the provider in the config file or use the `--provider` flag. The possible options for `--provider` are:
> LLMX also allows you to use other providers that support the OpenAI Chat Completions API. You can set the provider in the config file or use the `--provider` flag. The possible options for `--provider` are:
>
> - openai (default)
> - openrouter
@@ -129,28 +129,28 @@ export OPENAI_API_KEY="your-api-key-here"
Run interactively:
```shell
codex
llmx
```
Or, run with a prompt as input (and optionally in `Full Auto` mode):
```shell
codex "explain this codebase to me"
llmx "explain this codebase to me"
```
```shell
codex --approval-mode full-auto "create the fanciest todo-list app"
llmx --approval-mode full-auto "create the fanciest todo-list app"
```
That's it - Codex will scaffold a file, run it inside a sandbox, install any
That's it - LLMX will scaffold a file, run it inside a sandbox, install any
missing dependencies, and show you the live result. Approve the changes and
they'll be committed to your working directory.
---
## Why Codex?
## Why LLMX?
Codex CLI is built for developers who already **live in the terminal** and want
LLMX CLI is built for developers who already **live in the terminal** and want
ChatGPT-level reasoning **plus** the power to actually run code, manipulate
files, and iterate - all under version control. In short, it's _chat-driven
development_ that understands and executes your repo.
@@ -165,7 +165,7 @@ And it's **fully open-source** so you can see and contribute to how it develops!
## Security model & permissions
Codex lets you decide _how much autonomy_ the agent receives and auto-approval policy via the
LLMX lets you decide _how much autonomy_ the agent receives and auto-approval policy via the
`--approval-mode` flag (or the interactive onboarding prompt):
| Mode | What the agent may do without asking | Still requires approval |
@@ -175,7 +175,7 @@ Codex lets you decide _how much autonomy_ the agent receives and auto-approval p
| **Full Auto** | <li>Read/write files <li> Execute shell commands (network disabled, writes limited to your workdir) | - |
In **Full Auto** every command is run **network-disabled** and confined to the
current working directory (plus temporary files) for defense-in-depth. Codex
current working directory (plus temporary files) for defense-in-depth. LLMX
will also show a warning/confirmation if you start in **auto-edit** or
**full-auto** while the directory is _not_ tracked by Git, so you always have a
safety net.
@@ -185,21 +185,21 @@ the network enabled, once we're confident in additional safeguards.
### Platform sandboxing details
The hardening mechanism Codex uses depends on your OS:
The hardening mechanism LLMX uses depends on your OS:
- **macOS 12+** - commands are wrapped with **Apple Seatbelt** (`sandbox-exec`).
- Everything is placed in a read-only jail except for a small set of
writable roots (`$PWD`, `$TMPDIR`, `~/.codex`, etc.).
writable roots (`$PWD`, `$TMPDIR`, `~/.llmx`, etc.).
- Outbound network is _fully blocked_ by default - even if a child process
tries to `curl` somewhere it will fail.
- **Linux** - there is no sandboxing by default.
We recommend using Docker for sandboxing, where Codex launches itself inside a **minimal
We recommend using Docker for sandboxing, where LLMX launches itself inside a **minimal
container image** and mounts your repo _read/write_ at the same path. A
custom `iptables`/`ipset` firewall script denies all egress except the
OpenAI API. This gives you deterministic, reproducible runs without needing
root on the host. You can use the [`run_in_container.sh`](../codex-cli/scripts/run_in_container.sh) script to set up the sandbox.
root on the host. You can use the [`run_in_container.sh`](../llmx-cli/scripts/run_in_container.sh) script to set up the sandbox.
---
@@ -220,10 +220,10 @@ The hardening mechanism Codex uses depends on your OS:
| Command | Purpose | Example |
| ------------------------------------ | ----------------------------------- | ------------------------------------ |
| `codex` | Interactive REPL | `codex` |
| `codex "..."` | Initial prompt for interactive REPL | `codex "fix lint errors"` |
| `codex -q "..."` | Non-interactive "quiet mode" | `codex -q --json "explain utils.ts"` |
| `codex completion <bash\|zsh\|fish>` | Print shell completion script | `codex completion bash` |
| `llmx` | Interactive REPL | `llmx` |
| `llmx "..."` | Initial prompt for interactive REPL | `llmx "fix lint errors"` |
| `llmx -q "..."` | Non-interactive "quiet mode" | `llmx -q --json "explain utils.ts"` |
| `llmx completion <bash\|zsh\|fish>` | Print shell completion script | `llmx completion bash` |
Key flags: `--model/-m`, `--approval-mode/-a`, `--quiet/-q`, and `--notify`.
@@ -231,9 +231,9 @@ Key flags: `--model/-m`, `--approval-mode/-a`, `--quiet/-q`, and `--notify`.
## Memory & project docs
You can give Codex extra instructions and guidance using `AGENTS.md` files. Codex looks for `AGENTS.md` files in the following places, and merges them top-down:
You can give LLMX extra instructions and guidance using `AGENTS.md` files. LLMX looks for `AGENTS.md` files in the following places, and merges them top-down:
1. `~/.codex/AGENTS.md` - personal global guidance
1. `~/.llmx/AGENTS.md` - personal global guidance
2. `AGENTS.md` at repo root - shared project notes
3. `AGENTS.md` in the current working directory - sub-folder/feature specifics
@@ -243,14 +243,14 @@ Disable loading of these files with `--no-project-doc` or the environment variab
## Non-interactive / CI mode
Run Codex head-less in pipelines. Example GitHub Action step:
Run LLMX head-less in pipelines. Example GitHub Action step:
```yaml
- name: Update changelog via Codex
- name: Update changelog via LLMX
run: |
npm install -g @openai/codex
npm install -g @llmx/llmx
export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
codex -a auto-edit --quiet "update CHANGELOG for next release"
llmx -a auto-edit --quiet "update CHANGELOG for next release"
```
Set `CODEX_QUIET_MODE=1` to silence interactive UI noise.
@@ -260,24 +260,24 @@ Set `CODEX_QUIET_MODE=1` to silence interactive UI noise.
Setting the environment variable `DEBUG=true` prints full API request and response details:
```shell
DEBUG=true codex
DEBUG=true llmx
```
---
## Recipes
Below are a few bite-size examples you can copy-paste. Replace the text in quotes with your own task. See the [prompting guide](https://github.com/openai/codex/blob/main/codex-cli/examples/prompting_guide.md) for more tips and usage patterns.
Below are a few bite-size examples you can copy-paste. Replace the text in quotes with your own task. See the [prompting guide](https://github.com/valknar/llmx/blob/main/llmx-cli/examples/prompting_guide.md) for more tips and usage patterns.
| ✨ | What you type | What happens |
| --- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 1 | `codex "Refactor the Dashboard component to React Hooks"` | Codex rewrites the class component, runs `npm test`, and shows the diff. |
| 2 | `codex "Generate SQL migrations for adding a users table"` | Infers your ORM, creates migration files, and runs them in a sandboxed DB. |
| 3 | `codex "Write unit tests for utils/date.ts"` | Generates tests, executes them, and iterates until they pass. |
| 4 | `codex "Bulk-rename *.jpeg -> *.jpg with git mv"` | Safely renames files and updates imports/usages. |
| 5 | `codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$"` | Outputs a step-by-step human explanation. |
| 6 | `codex "Carefully review this repo, and propose 3 high impact well-scoped PRs"` | Suggests impactful PRs in the current codebase. |
| 7 | `codex "Look for vulnerabilities and create a security review report"` | Finds and explains security bugs. |
| 1 | `llmx "Refactor the Dashboard component to React Hooks"` | LLMX rewrites the class component, runs `npm test`, and shows the diff. |
| 2 | `llmx "Generate SQL migrations for adding a users table"` | Infers your ORM, creates migration files, and runs them in a sandboxed DB. |
| 3 | `llmx "Write unit tests for utils/date.ts"` | Generates tests, executes them, and iterates until they pass. |
| 4 | `llmx "Bulk-rename *.jpeg -> *.jpg with git mv"` | Safely renames files and updates imports/usages. |
| 5 | `llmx "Explain what this regex does: ^(?=.*[A-Z]).{8,}$"` | Outputs a step-by-step human explanation. |
| 6 | `llmx "Carefully review this repo, and propose 3 high impact well-scoped PRs"` | Suggests impactful PRs in the current codebase. |
| 7 | `llmx "Look for vulnerabilities and create a security review report"` | Finds and explains security bugs. |
---
@@ -287,13 +287,13 @@ Below are a few bite-size examples you can copy-paste. Replace the text in quote
<summary><strong>From npm (Recommended)</strong></summary>
```bash
npm install -g @openai/codex
npm install -g @llmx/llmx
# or
yarn global add @openai/codex
yarn global add @llmx/llmx
# or
bun install -g @openai/codex
bun install -g @llmx/llmx
# or
pnpm add -g @openai/codex
pnpm add -g @llmx/llmx
```
</details>
@@ -303,8 +303,8 @@ pnpm add -g @openai/codex
```bash
# Clone the repository and navigate to the CLI package
git clone https://github.com/openai/codex.git
cd codex/codex-cli
git clone https://github.com/valknar/llmx.git
cd llmx/llmx-cli
# Enable corepack
corepack enable
@@ -332,7 +332,7 @@ pnpm link
## Configuration guide
Codex configuration files can be placed in the `~/.codex/` directory, supporting both YAML and JSON formats.
LLMX configuration files can be placed in the `~/.llmx/` directory, supporting both YAML and JSON formats.
### Basic configuration parameters
@@ -365,7 +365,7 @@ In the `history` object, you can configure conversation history settings:
### Configuration examples
1. YAML format (save as `~/.codex/config.yaml`):
1. YAML format (save as `~/.llmx/config.yaml`):
```yaml
model: o4-mini
@@ -374,7 +374,7 @@ fullAutoErrorMode: ask-user
notify: true
```
2. JSON format (save as `~/.codex/config.json`):
2. JSON format (save as `~/.llmx/config.json`):
```json
{
@@ -455,7 +455,7 @@ Below is a comprehensive example of `config.json` with multiple custom providers
### Custom instructions
You can create a `~/.codex/AGENTS.md` file to define custom guidance for the agent:
You can create a `~/.llmx/AGENTS.md` file to define custom guidance for the agent:
```markdown
- Always respond with emojis
@@ -485,9 +485,9 @@ export OPENROUTER_API_KEY="your-openrouter-key-here"
## FAQ
<details>
<summary>OpenAI released a model called Codex in 2021 - is this related?</summary>
<summary>OpenAI released a model called LLMX in 2021 - is this related?</summary>
In 2021, OpenAI released Codex, an AI system designed to generate code from natural language prompts. That original Codex model was deprecated as of March 2023 and is separate from the CLI tool.
In 2021, OpenAI released LLMX, an AI system designed to generate code from natural language prompts. That original LLMX model was deprecated as of March 2023 and is separate from the CLI tool.
</details>
@@ -505,15 +505,15 @@ It's possible that your [API account needs to be verified](https://help.openai.c
</details>
<details>
<summary>How do I stop Codex from editing my files?</summary>
<summary>How do I stop LLMX from editing my files?</summary>
Codex runs model-generated commands in a sandbox. If a proposed command or file change doesn't look right, you can simply type **n** to deny the command or give the model feedback.
LLMX runs model-generated commands in a sandbox. If a proposed command or file change doesn't look right, you can simply type **n** to deny the command or give the model feedback.
</details>
<details>
<summary>Does it work on Windows?</summary>
Not directly. It requires [Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/install) - Codex is regularly tested on macOS and Linux with Node 20+, and also supports Node 16.
Not directly. It requires [Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/install) - LLMX is regularly tested on macOS and Linux with Node 20+, and also supports Node 16.
</details>
@@ -521,24 +521,24 @@ Not directly. It requires [Windows Subsystem for Linux (WSL2)](https://learn.mic
## Zero data retention (ZDR) usage
Codex CLI **does** support OpenAI organizations with [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) enabled. If your OpenAI organization has Zero Data Retention enabled and you still encounter errors such as:
LLMX CLI **does** support OpenAI organizations with [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) enabled. If your OpenAI organization has Zero Data Retention enabled and you still encounter errors such as:
```
OpenAI rejected the request. Error details: Status: 400, Code: unsupported_parameter, Type: invalid_request_error, Message: 400 Previous response cannot be used for this organization due to Zero Data Retention.
```
You may need to upgrade to a more recent version with: `npm i -g @openai/codex@latest`
You may need to upgrade to a more recent version with: `npm i -g @llmx/llmx@latest`
---
## Codex open source fund
## LLMX open source fund
We're excited to launch a **$1 million initiative** supporting open source projects that use Codex CLI and other OpenAI models.
We're excited to launch a **$1 million initiative** supporting open source projects that use LLMX CLI and other OpenAI models.
- Grants are awarded up to **$25,000** API credits.
- Applications are reviewed **on a rolling basis**.
**Interested? [Apply here](https://openai.com/form/codex-open-source-fund/).**
**Interested? [Apply here](https://openai.com/form/llmx-open-source-fund/).**
---
@@ -591,7 +591,7 @@ pnpm format:fix
### Debugging
To debug the CLI with a visual debugger, do the following in the `codex-cli` folder:
To debug the CLI with a visual debugger, do the following in the `llmx-cli` folder:
- Run `pnpm run build` to build the CLI, which will generate `cli.js.map` alongside `cli.js` in the `dist` folder.
- Run the CLI with `node --inspect-brk ./dist/cli.js` The program then waits until a debugger is attached before proceeding. Options:
@@ -602,7 +602,7 @@ To debug the CLI with a visual debugger, do the following in the `codex-cli` fol
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.
3. **Document behaviour.** If your change affects user-facing behaviour, update the README, inline help (`llmx --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
@@ -628,7 +628,7 @@ To debug the CLI with a visual debugger, do the following in the `codex-cli` fol
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:
Together we can make LLMX CLI an incredible tool. **Happy hacking!** :rocket:
### Contributor license agreement (CLA)
@@ -653,11 +653,11 @@ No special Git commands, email attachments, or commit footers required.
The **DCO check** blocks merges until every commit in the PR carries the footer (with squash this is just the one).
### Releasing `codex`
### Releasing `llmx`
To publish a new version of the CLI you first need to stage the npm package. A
helper script in `codex-cli/scripts/` does all the heavy lifting. Inside the
`codex-cli` folder run:
helper script in `llmx-cli/scripts/` does all the heavy lifting. Inside the
`llmx-cli` folder run:
```bash
# Classic, JS implementation that includes small, native binaries for Linux sandboxing.
@@ -689,27 +689,27 @@ Enter a Nix development shell:
```bash
# Use either one of the commands according to which implementation you want to work with
nix develop .#codex-cli # For entering codex-cli specific shell
nix develop .#codex-rs # For entering codex-rs specific shell
nix develop .#llmx-cli # For entering llmx-cli specific shell
nix develop .#llmx-rs # For entering llmx-rs specific shell
```
This shell includes Node.js, installs dependencies, builds the CLI, and provides a `codex` command alias.
This shell includes Node.js, installs dependencies, builds the CLI, and provides a `llmx` command alias.
Build and run the CLI directly:
```bash
# Use either one of the commands according to which implementation you want to work with
nix build .#codex-cli # For building codex-cli
nix build .#codex-rs # For building codex-rs
./result/bin/codex --help
nix build .#llmx-cli # For building llmx-cli
nix build .#llmx-rs # For building llmx-rs
./result/bin/llmx --help
```
Run the CLI via the flake app:
```bash
# Use either one of the commands according to which implementation you want to work with
nix run .#codex-cli # For running codex-cli
nix run .#codex-rs # For running codex-rs
nix run .#llmx-cli # For running llmx-cli
nix run .#llmx-rs # For running llmx-rs
```
Use direnv with flakes
@@ -717,10 +717,10 @@ Use direnv with flakes
If you have direnv installed, you can use the following `.envrc` to automatically enter the Nix shell when you `cd` into the project directory:
```bash
cd codex-rs
echo "use flake ../flake.nix#codex-cli" >> .envrc && direnv allow
cd codex-cli
echo "use flake ../flake.nix#codex-rs" >> .envrc && direnv allow
cd llmx-rs
echo "use flake ../flake.nix#llmx-cli" >> .envrc && direnv allow
cd llmx-cli
echo "use flake ../flake.nix#llmx-rs" >> .envrc && direnv allow
```
---

8
llmx-cli/scripts/README.md
View File

@@ -6,14 +6,14 @@ example, to stage the CLI, responses proxy, and SDK packages for version `0.6.0`
```bash
./scripts/stage_npm_packages.py \
--release-version 0.6.0 \
--package codex \
--package codex-responses-api-proxy \
--package codex-sdk
--package llmx \
--package llmx-responses-api-proxy \
--package llmx-sdk
```
This downloads the native artifacts once, hydrates `vendor/` for each package, and writes
tarballs to `dist/npm/`.
If you need to invoke `build_npm_package.py` directly, run
`codex-cli/scripts/install_native_deps.py` first and pass `--vendor-src` pointing to the
`llmx-cli/scripts/install_native_deps.py` first and pass `--vendor-src` pointing to the
directory that contains the populated `vendor/` tree.