1. ✨ Project introduction

The official Codex CLI does not expose the Desktop Projects view as a project-management interface. Codex can work inside a directory, but building a dashboard or workbench that orchestrates many agents also needs a dependable way to discover projects, follow session relationships, and manage project folders.

codex-project is that missing command layer: an unofficial, safety-first CLI over local Codex Desktop metadata.

| | What it provides | |---:|---| | 🔎 | Visible, hidden, and stale project discovery with session detail | | 📁 | Exact project selection and ordered folder management | | 🩺 | Read-only diagnostics for state, relationships, folders, and backups | | 🛡️ | Dry runs, Desktop lifecycle guards, locking, exact backups, atomic writes, and rollback | | 🤖 | Human-friendly terminal output and stable schemaVersion: 1 JSON for agents |

[!WARNING] codex-project targets undocumented local Desktop state, not a public Codex API. A Desktop update may change that schema. Always preview mutations with --dry-run; real changes fail closed on unsafe state and create a byte-for-byte backup before replacement.

2. 🚀 Quick start

Install the published package—no local build is required:

npm install -g @chiphoton/codex-project

codex-project --version
codex-project --help

🧰 Command guide

| Command | Use | |---|---| | codex-project list [project...] [--all] [--json] | List projects; an exact ID, name, or folder adds session detail | | codex-project doctor [project...] [--verbose] [--json] | Diagnose project, folder, session, and state relationships | | codex-project doctor backups [--json] | Inspect timestamped full-state backups | | codex-project add <folder...> [--name <name>] | Add a project or restore a hidden one | | codex-project rename <project> <new-name> | Rename one visible or hidden project | | codex-project folder list <project> [--json] | Show registered folders and primary/present status | | codex-project folder add\|remove\|replace\|primary ... | Change registered project folders | | codex-project remove <project...> [--deep] | Hide projects, or remove project relationships with --deep |

Start read-only, then preview every mutation:

codex-project list --all
codex-project doctor

codex-project add /absolute/path/to/app --name "My App" --dry-run

Review the preview, stop Codex Desktop, and only then repeat without --dry-run. Mutation commands also accept --quit, --wait, and long-form --force; the CLI never force-kills Desktop.

3. 🪄 Common workflow

👤 For humans — calm, readable output

codex-project list --all
codex-project list "My Project"
codex-project folder list "My Project"
codex-project doctor

Interactive terminals receive bold project names, green/gray status, highlighted folder and session counts, blue IDs, severity-aware diagnostics, and clickable folder paths. Redirects stay plain. Use NO_COLOR=1 or NO_HYPERLINKS=1 when needed.

🤖 For agents — structured JSON

codex-project list --all --json
codex-project list "My Project" --json
codex-project folder list "My Project" --json
codex-project doctor --json
codex-project doctor backups --json

JSON is written only to stdout, contains no ANSI or hyperlink escapes, and includes schemaVersion: 1. Exit status 4 means doctor completed successfully and found a warning or error; it does not mean the command crashed.

4. 🧑‍💻 Development

npm ci
npm run dev -- list --all
npm run check
npm run build
npm run package

| Command | Result | |---|---| | npm run dev -- <args> | Build and run the local CLI with the supplied arguments | | npm run check | Run Biome, TypeScript, all Vitest tests, and the production build | | npm run build | Compile the runtime into dist/ | | npm run package | Create the publishable .tgz inside build/ | | npm run package -- --dry-run | Inspect package contents without creating the tarball |

Install the locally packed release with:

npm install -g ./build/chiphoton-codex-project-0.1.4.tgz

Tests use sanitized fixtures and temporary explicit Codex homes; they never discover or modify the user's live Codex state.

5. 🔌 Known issues

• 🧩 Private schema: Desktop metadata is undocumented and may change; mutations deliberately reject unknown unsafe shapes.
• 🖥️ Desktop lifecycle: read-only commands may run while Desktop is open, but mutations require verified shutdown.
• ☁️ Local projects only: ChatGPT cloud projects are outside this CLI's scope.
• 🪟 Platform boundary: native macOS and Windows are supported; CLI execution inside WSL and final real-Windows release validation remain pending.
• 🧰 Deferred commands: export/import, deterministic doctor fix/recover, and shell completion are not implemented yet.
• 🖱️ Terminal differences: OSC 8 folder links depend on terminal support, and terminals provide no portable click-to-copy action for IDs.
• 🗃️ Deep removal: project relationships can be removed, but session index entries and transcript files are intentionally never deleted.

For the precise state, selector, mutation, and exit-code rules, read the CLI contract.