+
+
+
+ A local browser workbench for Codex CLI. +
+ +
+ 
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](#alpha-status)
+- [Why CodexClaw](#why-codexclaw)
+- [Quick Start](#quick-start)
+- [NPM Alpha](#npm-alpha)
+- [Terminal Demo](#terminal-demo)
+- [Configuration](#configuration)
+- [Common Commands](#common-commands)
+- [How It Works](#how-it-works)
+- [Beta Track](#beta-track)
+- [Contributing](#contributing)
-
+## Alpha Status
-CodexClaw is a local web client for Codex CLI. It gives you a browser-based chat surface, local session history, and a small project bootstrapper while still running prompts through your own installed `codex` command.
+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.
-[](#alpha-status)
-[](#how-it-works)
-[](LICENSE)
+Use it for local experimentation with Codex CLI. Do not treat it as a production interface yet.
-## Alpha Status
+## Why CodexClaw
-CodexClaw is public alpha software. The core local loop works today, but the project is intentionally marked in progress while streaming, attachments, packaging, and release checks are hardened.
+| 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 |
-Use it if you want to try a local Codex CLI web surface and do not mind rough edges. Avoid relying on it as a production interface yet.
+## Quick Start
-## What It Does
+~~~bash
+git clone https://github.com/slashdevcorpse/codex-claw.git
+cd codex-claw
+pnpm install
+pnpm dev
+~~~
-- Runs prompts through local `codex exec --json`
-- Stores local chat sessions in `.codex-claw/sessions.json`
-- Provides a React chat UI with sessions, history, rename, delete, and export controls
-- Includes a `codex-claw` CLI for project bootstrap and local environment checks
-- Keeps configuration server-side through `.env.local`
+Open [http://localhost:3000](http://localhost:3000).
-## Requirements
+Requirements:
- Node.js 20 or newer
- pnpm
@@ -31,98 +66,114 @@ Use it if you want to try a local Codex CLI web surface and do not mind rough ed
Check Codex CLI first:
-```bash
+~~~bash
codex --version
codex exec "Reply with: ready"
-```
+~~~
-## Quick Start
+## NPM Alpha
-```bash
-git clone https://github.com/slashdevcorpse/codex-claw.git
-cd codex-claw
-pnpm install
-pnpm dev
-```
+The public npm package target is codex-claw@0.1.0-alpha.0.
-Open [http://localhost:3000](http://localhost:3000).
+After the first npm alpha publish, the install path will be:
+
+~~~bash
+npx codex-claw@alpha
+~~~
+
+Until then, use the source checkout above. The package is intentionally tagged as alpha so early releases do not claim a stable latest workflow.
-By default, CodexClaw runs the app at `apps/codex-claw` and starts Vite on port 3000.
+## Terminal Demo
+
+Target first-run flow:
+
+~~~console
+$ 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:
+
+~~~console
+$ node packages/codex-claw/bin/codex-claw.js doctor
+Environment looks good.
+~~~
+
+Manual source workflow:
+
+~~~console
+$ 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.
+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.
-```bash
+~~~bash
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 |
-
-## CLI Usage
-
-The local CLI package is in `packages/codex-claw`.
-
-```bash
-pnpm -C packages/codex-claw exec codex-claw --help
-pnpm -C packages/codex-claw exec codex-claw doctor
-```
-
-After the first npm alpha publish, the intended install command is:
-
-```bash
-npx codex-claw@alpha
-```
+| 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
-```bash
+~~~bash
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 release:codex-claw # publish alpha package with the alpha dist-tag
+~~~
## How It Works
-The browser talks to local server routes in the app. Those routes call a local adapter in `apps/codex-claw/src/server/codex-cli.ts`, which launches Codex CLI with `codex exec --json` and writes session data to disk.
-
-```text
+~~~text
Browser UI
-> app API routes
-> local Codex CLI adapter
-> codex exec --json
-> .codex-claw/sessions.json
-```
+~~~
-This means prompts run on your machine, with your Codex CLI auth and your configured working directory.
+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.
-## Current Limitations
+## Beta Track
-- Responses appear after Codex CLI returns a completed assistant message; progressive streaming is not complete yet.
-- Image attachments are visible in the UI but are not passed through to Codex CLI yet.
-- The npm package is prepared as `0.1.0-alpha.0` but has not been published yet.
-- Session storage is local JSON, not a multi-user database.
-- CI and release automation are still being added.
+CodexClaw can move from alpha toward beta when these workflows are reliable:
+
+- Progressive Codex CLI streaming
+- Image attachment pass-through to Codex CLI
+- npm alpha publish through npx codex-claw@alpha
+- release checklist for package contents, smoke tests, and docs
+- CI coverage for app build, tests, lint, and package dry run
## Project Layout
-```text
+~~~text
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
@@ -139,4 +190,3 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
## License
MIT. See [LICENSE](LICENSE).
-
diff --git a/package.json b/package.json
index 8e49269..3777a50 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,8 @@
"lint": "pnpm -C apps/codex-claw lint",
"format": "pnpm -C apps/codex-claw format",
"check": "pnpm -C apps/codex-claw check",
- "release:codex-claw": "pnpm -C packages/codex-claw exec npm publish --access public",
+ "pack:codex-claw": "pnpm -C packages/codex-claw exec npm pack --dry-run",
+ "release:codex-claw": "pnpm -C packages/codex-claw exec npm publish --tag alpha --access public",
"bump:codex-claw:patch": "pnpm -C packages/codex-claw version patch --no-git-tag-version",
"bump:codex-claw:minor": "pnpm -C packages/codex-claw version minor --no-git-tag-version",
"bump:codex-claw:major": "pnpm -C packages/codex-claw version major --no-git-tag-version",
diff --git a/packages/codex-claw/README.md b/packages/codex-claw/README.md
index 04c6dd7..c84d2c1 100644
--- a/packages/codex-claw/README.md
+++ b/packages/codex-claw/README.md
@@ -1,32 +1,61 @@
# codex-claw
-Alpha CLI for CodexClaw, a local web client for Codex CLI.
+Alpha CLI for CodexClaw, a local browser workbench for Codex CLI.
-The CLI bootstraps a CodexClaw project, writes local Codex CLI defaults when requested, and checks that the machine has the runtime tools needed to start the app.
+The package is designed for an npx codex-claw@alpha first-run workflow. It can bootstrap a CodexClaw project, write Codex CLI defaults, start the app, and run project checks from an existing checkout.
+
+## Status
+
+- Package name: codex-claw
+- Current version: 0.1.0-alpha.0
+- Release channel: alpha
+- Runtime dependency: your installed and authenticated Codex CLI
## Requirements
- Node.js 20 or newer
-- pnpm
- Git
- Codex CLI installed and logged in
+- pnpm for local development workflows
+
+## Alpha Install
+
+After the first public npm publish:
+
+~~~bash
+npx codex-claw@alpha
+~~~
+
+Useful non-interactive bootstrap:
+
+~~~bash
+npx codex-claw@alpha --yes --no-start --project-name codex-claw-demo
+cd codex-claw-demo
+pnpm install
+pnpm dev
+~~~
## Local Development Usage
From this repository:
-```bash
-pnpm -C packages/codex-claw exec codex-claw --help
-pnpm -C packages/codex-claw exec codex-claw doctor
-```
+~~~bash
+node packages/codex-claw/bin/codex-claw.js --help
+node packages/codex-claw/bin/codex-claw.js doctor
+~~~
-## Intended Alpha Install
-
-After the first npm alpha publish:
+## Commands
-```bash
-npx codex-claw@alpha
-```
+| Command | Purpose |
+| --- | --- |
+| codex-claw | Create and start a project |
+| codex-claw init [dir] | Initialize a project in a directory |
+| codex-claw dev | Start the app dev server |
+| codex-claw build | Build the app |
+| codex-claw preview | Preview the production build |
+| codex-claw test | Run tests |
+| codex-claw lint | Run lint |
+| codex-claw doctor | Validate Node.js, pnpm, and Codex CLI |
## Prompts
@@ -38,27 +67,24 @@ The bootstrap flow asks for:
- optional Codex CLI working directory
- local dev port
-Then it creates the project folder, installs dependencies, and starts CodexClaw unless `--no-start` is provided.
-
-## Commands
-
-```bash
-codex-claw create and start a project
-codex-claw init [dir] initialize a project in a directory
-codex-claw dev start the app dev server
-codex-claw build build the app
-codex-claw preview preview the production build
-codex-claw test run tests
-codex-claw lint run lint
-codex-claw doctor validate Node.js, pnpm, and Codex CLI
-```
+Then it creates the project folder, installs dependencies, and starts CodexClaw unless --no-start is provided.
## Environment
| Variable | Default | Purpose |
| --- | --- | --- |
-| `CODEX_CLI_COMMAND` | `codex` | Command used by the app 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 |
+| CODEX_CLI_COMMAND | codex | Command used by the app 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 |
+
+## Publish Checklist
+
+~~~bash
+npm whoami
+npm view codex-claw version dist-tags --json
+pnpm pack:codex-claw
+pnpm release:codex-claw
+~~~
+The release script publishes with the alpha dist-tag so early builds stay clearly separated from a future stable channel.
diff --git a/packages/codex-claw/bin/codex-claw.js b/packages/codex-claw/bin/codex-claw.js
index b79a840..1a73148 100755
--- a/packages/codex-claw/bin/codex-claw.js
+++ b/packages/codex-claw/bin/codex-claw.js
@@ -26,7 +26,7 @@ function printHelp() {
process.stdout.write(`codex-claw CLI\n\n`)
process.stdout.write(`Usage:\n`)
process.stdout.write(` codex-claw Create and start a new project\n`)
- process.stdout.write(` codex-claw init [dir] Initialize a new project (legacy)\n`)
+ process.stdout.write(` codex-claw init [dir] Initialize a project in a directory\n`)
process.stdout.write(` codex-claw dev Run development server\n`)
process.stdout.write(` codex-claw build Build project\n`)
process.stdout.write(` codex-claw preview Preview production build\n`)
diff --git a/packages/codex-claw/package.json b/packages/codex-claw/package.json
index 88860b9..2d9ebb2 100644
--- a/packages/codex-claw/package.json
+++ b/packages/codex-claw/package.json
@@ -2,7 +2,7 @@
"name": "codex-claw",
"version": "0.1.0-alpha.0",
"private": false,
- "description": "CodexClaw alpha CLI",
+ "description": "Local Codex CLI web-client bootstrapper for the CodexClaw alpha.",
"type": "module",
"bin": {
"codex-claw": "bin/codex-claw.js"
@@ -15,10 +15,23 @@
"codex-claw",
"codex",
"codex-cli",
+ "codex-cli-ui",
+ "developer-tools",
+ "local-first",
"cli"
],
"license": "MIT",
+ "homepage": "https://github.com/slashdevcorpse/codex-claw#readme",
+ "bugs": {
+ "url": "https://github.com/slashdevcorpse/codex-claw/issues"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/slashdevcorpse/codex-claw.git",
+ "directory": "packages/codex-claw"
+ },
"publishConfig": {
+ "tag": "alpha",
"access": "public"
},
"engines": {