# ddev-codex-claude-cli

`ddev-codex-claude-cli` is a DDEV add-on that runs Codex CLI and Claude Code CLI inside the DDEV `web` container while keeping runtime state under the project's `.ddev` directory on the host (bind-mounted into the container).

## What it does

- exposes `ddev codex`
- exposes `ddev claude`
- optionally exposes `ddev claude-swap` for juggling multiple Claude accounts (opt-in; see [Multiple Claude accounts](#multiple-claude-accounts))
- installs Codex CLI lazily the first time you run `ddev codex` (or whenever the persisted binary is missing) by downloading the latest release from GitHub: `curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh`
- installs Claude Code CLI during `ddev start` when the persisted binary is missing or broken by downloading the stable native build: `curl -fsSL https://claude.ai/install.sh | bash -s stable`
- keeps normal `ddev start` fast by skipping Claude Code installation when the persisted binary is already runnable
- persists each CLI's binary, HOME, and XDG paths under **project-local** storage so each DDEV project has its own profiles
- seeds the project-local HOME from the container home on first bootstrap for `.gitignore_global` when present
- always runs Codex with `--sandbox danger-full-access --ask-for-approval untrusted`

## Runtime storage

Inside the web container, Codex CLI state lives under:

    ${DDEV_APPROOT}/.ddev/codex-cli

Claude Code CLI state lives under:

    ${DDEV_APPROOT}/.ddev/claude-code

On the host, those are your project's **`.ddev/codex-cli/`** and **`.ddev/claude-code/`** directories. They survive `ddev restart`, `ddev stop`, and `ddev poweroff` like any other project file. The same directories hold the add-on's **install scripts** (managed files) alongside runtime data created after the first start.

Codex layout:

| Path | Role |
|------|------|
| `.ddev/codex-cli/install.sh` | Codex install script |
| `.ddev/codex-cli/bin/codex` | Codex CLI binary |
| `.ddev/codex-cli/home` | `HOME` |
| `.ddev/codex-cli/config` | `XDG_CONFIG_HOME` |
| `.ddev/codex-cli/data` | `XDG_DATA_HOME` |
| `.ddev/codex-cli/state` | `XDG_STATE_HOME` |

Claude Code layout:

| Path | Role |
|------|------|
| `.ddev/claude-code/install.sh` | Claude Code install script |
| `.ddev/claude-code/home/.local/bin/claude` | Claude Code CLI binary |
| `.ddev/claude-code/home` | `HOME` |
| `.ddev/claude-code/config` | `XDG_CONFIG_HOME` |
| `.ddev/claude-code/data` | `XDG_DATA_HOME` |
| `.ddev/claude-code/state` | `XDG_STATE_HOME` |

Authentication and settings are **per project**: sign in once per project; they persist across container restarts.

## Install

From a DDEV project root:

    ddev add-on get /path/to/ddev-codex-claude-cli

Then restart:

    ddev restart

## Usage

    ddev codex

    ddev codex --version

    ddev claude

    ddev claude --version

    ddev claude update

    ddev claude-swap list              # opt-in; see "Multiple Claude accounts"

## Updates

Codex CLI is installed lazily when `ddev codex` runs and the persisted binary is missing or broken.

Claude Code CLI is installed automatically on `ddev start` only when the persisted binary is missing or broken. Later starts run a fast health check and skip installation when Claude is already runnable.

To check for and install a newer Claude Code stable release, run:

    ddev claude update

## Multiple Claude accounts

The add-on can integrate [`claude-swap`](https://github.com/realiti4/claude-swap)
(`cswap`) so one project can hold several Claude accounts and swap between them —
mainly to keep working past a 5-hour or weekly rate limit. It is **opt-in**: nothing
is installed during `ddev start`; the first `ddev claude-swap` call (or first
`ddev claude --account …`) installs `uv` and `claude-swap` into the project-local
Claude profile under `.ddev/claude-code/`.

Accounts are stored **per project**, next to the rest of the Claude state:

    .ddev/claude-code/data/claude-swap/

They persist across restarts and are deleted when the add-on is removed. Back them up
first with `ddev claude-swap export backup.cswap` if you need to keep them.

### Swapping accounts without losing your session

A running `ddev claude` conversation is not tied to the auth token, and Claude Code
re-reads its credentials file whenever it changes. So:

1. Terminal 1: you are in `ddev claude`, working, and hit (or approach) the limit.
2. Terminal 2 (on the host): `ddev claude-swap switch <n|email|alias>`
   (or `ddev claude-swap switch --strategy best`).
3. Back in terminal 1: send the next message — it goes out on the new account, in the
   **same session** with all its context. If a request just failed with the limit
   error, resend it.

To automate step 2, run `ddev claude-swap auto` in a spare terminal (or an
`ddev ssh` shell); it watches usage and switches around 90%.

### One-time setup

    ddev claude                     # sign in as your first account
    ddev claude-swap add --alias a  # capture it
    ddev claude                     # /login inside Claude Code as the next account, then exit
    ddev claude-swap add --alias b  # capture it
    ddev claude-swap list           # all accounts with usage and reset times
    ddev claude-swap status         # currently active account

`ddev claude-swap` forwards every argument straight to `cswap`, so any `cswap`
subcommand works (`switch`, `run`, `map`, `disable`, `export`, `import`, `tui`, …).
`ddev claude-swap upgrade` updates `claude-swap` to the latest release.

### Starting a session pinned to an account

Separately from the hot-swap flow, you can launch a session bound to one account
(with its own per-account chat history):

    ddev claude --account b
    ddev claude --account b --resume    # remaining args pass straight to Claude Code

Set a project default so plain `ddev claude` always uses it:

    echo b > .ddev/claude-code/claude-swap-account
    # or export DDEV_CLAUDE_SWAP_ACCOUNT=b

Remove the file (or unset the variable) to go back to the normal single-account
launch.

### Requirements

The first install needs outbound network access to `astral.sh`, `pypi.org`,
`files.pythonhosted.org`, and `github.com` (for the `uv`-managed Python 3.12).
`claude-swap` captures whichever account is signed in at `cswap add` time, so the
initial multi-account setup is a few manual `/login` round-trips.

## Installed managed files

    .ddev/config.codex-cli.yaml
    .ddev/config.claude-code.yaml
    .ddev/commands/web/codex
    .ddev/commands/web/claude
    .ddev/commands/web/claude-swap
    .ddev/codex-cli/install.sh
    .ddev/claude-code/install.sh
    .ddev/claude-code/install-swap.sh

## Notes

- the first `ddev codex` in a project can take some time because it downloads the Codex CLI binary; later runs reuse `.ddev/codex-cli/bin/codex`
- the first `ddev start` after installing the add-on can take some time because it downloads Claude Code; later starts reuse `.ddev/claude-code/home/.local/bin/claude`
- if the container home has `.gitignore_global` (typically from host `~/.ddev/homeadditions/.gitignore_global`), it is copied into each project-local CLI `HOME` on first bootstrap; git's `core.excludesfile` is pointed at that project-local copy
- if you do not want add-on or CLI runtime files in your repository, ignore them in git, for example:

      /.ddev/addon-metadata/ddev-codex-claude-cli
      /.ddev/config.codex-cli.yaml
      /.ddev/config.claude-code.yaml
      /.ddev/commands/web/codex
      /.ddev/commands/web/claude
      /.ddev/commands/web/claude-swap
      /.ddev/codex-cli/
      /.ddev/claude-code/

Removing the add-on deletes `.ddev/codex-cli/` and `.ddev/claude-code/` as well (local auth, config, and CLI binaries). Back up those directories first if you need to keep them.

## macOS / Linux / WSL2

This add-on runs Codex CLI and Claude Code CLI in the DDEV container, so host OS differences are minimized as long as DDEV works normally.