CodexClaw

A local browser workbench for Codex CLI.

CodexClaw turns your installed codex command into a local web client with chat sessions, history, exports, and a small bootstrap CLI. Prompts still run through your own Codex CLI auth, on your machine, against the workspace you configure.

Contents

• Alpha Status
• Why CodexClaw
• Quick Start
• NPM Alpha
• Terminal Demo
• Configuration
• Common Commands
• Troubleshooting
• How It Works
• Beta Track
• Contributing

Alpha Status

CodexClaw is public alpha software. The core local loop works today, but the project is still hardening streaming, attachments, npm release automation, and beta-quality verification.

Use it for local experimentation with Codex CLI. Do not treat it as a production interface yet.

Why CodexClaw

Need	What CodexClaw gives you
Browser workflow	A local React chat surface for Codex CLI sessions
Local control	Prompts run through codex exec --json with your local auth
Session memory	Conversation history is stored in .codex-claw/sessions.json
Project bootstrap	codex-claw can create a fresh local CodexClaw workspace
Safer defaults	The app defaults Codex CLI sandboxing to read-only

Quick Start

git clone https://github.com/slashdevcorpse/codex-claw.git
cd codex-claw
pnpm install
pnpm dev

Open http://localhost:3000.

Requirements:

• Node.js 20 or newer
• pnpm
• Git
• Codex CLI installed and logged in

Check Codex CLI first:

codex --version
codex exec "Reply with: ready"

NPM Alpha

The public npm package target is codex-claw@0.1.0-alpha.1.

After the first npm alpha publish, start without a global install:

# Windows PowerShell
npx codex-claw@alpha
npm exec codex-claw@alpha -- doctor

# macOS and Linux
npx codex-claw@alpha
npm exec codex-claw@alpha -- doctor

For a pinned global CLI during alpha:

npm install -g codex-claw@alpha
codex-claw doctor
codex-claw --help

Update by re-running npx codex-claw@alpha or reinstalling the alpha tag:

npm install -g codex-claw@alpha

Until the first alpha package exists on npm, use the source checkout above. The package is intentionally tagged as alpha so early releases do not claim a stable latest workflow.

Terminal Demo

Target first-run flow:

$ npx codex-claw@alpha --help
codex-claw CLI

Usage:
  codex-claw                 Create and start a new project
  codex-claw init [dir]      Initialize a project in a directory
  codex-claw dev             Run development server
  codex-claw doctor          Validate local setup

Local source readiness check:

$ node packages/codex-claw/bin/codex-claw.js doctor
[ok] Node.js: Node.js 20.19.5
[ok] npm: 10.8.2
[warn] npm auth: npm auth unavailable. Run `npm login` before publishing codex-claw@alpha.
[ok] pnpm: 9.15.4
[ok] git: git version 2.51.0.windows.1
[ok] git worktree: Current directory is a git worktree.
[ok] Codex CLI: codex-cli 0.61.0
[ok] state directory: .codex-claw can be created on first run.
[ok] port: Port 3000 is available.
Environment is usable with 1 warning(s).

Manual source workflow:

$ pnpm dev
VITE v6.x ready
Local: http://localhost:3000/

Configuration

CodexClaw works with no extra configuration when codex is available on PATH. Add apps/codex-claw/.env.local only when you need to override defaults.

CODEX_CLI_COMMAND=codex
CODEX_CLI_SANDBOX=read-only
CODEX_CLI_WORKDIR=C:/path/to/project
CODEX_CLAW_STATE_DIR=C:/path/to/codex-claw-state

Variable	Default	Purpose
CODEX_CLI_COMMAND	codex	Command used by the server to launch Codex CLI
CODEX_CLI_SANDBOX	read-only	Sandbox mode passed to Codex CLI
CODEX_CLI_WORKDIR	app process cwd	Workspace directory for Codex CLI runs
CODEX_CLAW_STATE_DIR	.codex-claw	Local session-history directory

Common Commands

pnpm dev                 # start the app
pnpm build               # build the app
pnpm test                # run app tests
pnpm lint                # run ESLint
pnpm landing:dev         # start the landing page
pnpm landing:build       # build the landing page
pnpm pack:codex-claw     # inspect npm package contents
pnpm smoke:codex-claw    # run npx against the packed local tarball
pnpm smoke:codex-claw:npm # run npx against codex-claw@alpha once published
pnpm release:codex-claw  # publish alpha package with the alpha dist-tag

Troubleshooting

Symptom	What to run
npm auth unavailable	Run npm login, then npm whoami before publishing
codex-claw@alpha was not found on npm	The alpha package has not been published yet; use the source checkout or publish with pnpm release:codex-claw
Port 3000 is already in use	Stop the process using the port or run codex-claw doctor --port 3001
Codex CLI was not found	Install Codex CLI, run codex login, or pass --codex-command <cmd>

Package readiness checks:

pnpm smoke:codex-claw:pack
pnpm smoke:codex-claw:npm

How It Works

Browser UI
  -> app API routes
  -> local Codex CLI adapter
  -> codex exec --json
  -> .codex-claw/sessions.json

The browser talks to local server routes in apps/codex-claw. Those routes call apps/codex-claw/src/server/codex-cli.ts, which launches Codex CLI and writes session data locally.

Beta Track

CodexClaw can move from alpha toward beta when these workflows are reliable:

• completed beta backlog features are merged and mapped in docs/BETA_WORKFLOW.md
• npm alpha publish works through npx codex-claw@alpha
• package dry run, packed smoke test, npm smoke test, app lint, app tests, and app build all pass
• release package tarball and SHA256 checksums are attached to a GitHub release
• redacted session bundle evidence is captured before public release notes are posted

Project Layout

apps/codex-claw/       React app and local server routes
apps/landing/          Public landing page
packages/codex-claw/   CLI package
pnpm-workspace.yaml    Workspace definition

Contributing

Small, focused changes are preferred during alpha. Good areas to work on:

• Codex CLI streaming support
• attachment pass-through
• CLI packaging and install polish
• tests around local session behavior
• documentation that makes setup clearer

Read CONTRIBUTING.md before opening a PR.

License

MIT. See LICENSE.