Codex Bare

Thin browser UI plus TypeScript client for codex app-server.

The current source is:

• apps/web: React/Vite UI that connects directly to a Codex app-server WebSocket.
• apps/cli: Bun CLI that sends JSON-RPC actions to a listening Codex app-server.
• apps/flow-runner: CLI for discovering and firing packaged flows.
• apps/flow-backend-systemd-local: local HTTP backend for executing flows from dispatch events.
• packages/codex-client: JSON-RPC client, app-server transports, flow helpers, and generated protocol types.
• packages/flow-runtime: flow manifest loading, event matching, and runner primitives.
• packages/ui: small shared UI primitives and styling.

Run

Install dependencies:

bun install

Start a Codex app-server WebSocket in a separate shell:

codex app-server --listen ws://127.0.0.1:3585 --enable apps --enable hooks

Start the web app:

bun run dev

In development, the web app defaults to a same-origin Vite WebSocket proxy at /__codex-app-server, which forwards to ws://127.0.0.1:3585. This avoids browser Origin header rejections from the app-server, which can show up in WSL and other browser-to-localhost setups.

Set VITE_CODEX_APP_SERVER_PROXY_TARGET to proxy to a different app-server URL. Set VITE_CODEX_APP_SERVER_WS_URL only when you explicitly want the browser to connect directly to an app-server WebSocket.

Send a command to the running app-server:

bun apps/cli/src/index.ts thread/list '{"limit": 20, "sourceKinds": []}'
echo '{"refreshToken": false}' | bun apps/cli/src/index.ts account/read

List available actions:

bun apps/cli/src/index.ts actions

Build And Test

bun run build
bun run test

bun run test runs the client, flow runtime, local flow backend, CLI, and Discord bridge tests.

Flow Automation

Flow packages live under flows/* and installed copies can live under .codex/flows/*. See docs/flows.md for flow.toml, generic FlowEvent dispatch, Bun and Code Mode runners, the systemd-local backend, and the Codex release flows.

bun run flow list
bun run flow:backend serve --cwd "$(pwd)"
bun run flow:backend list-events --limit 20
bun run flow:backend list-runs --status failed

Code Mode flow steps are present on main behind one mode flag:

CODEX_FLOWS_MODE=code-mode

That mode enables runner = "code-mode" steps and makes stdio app-server launches default to bunx @peezy.tech/codex. CODEX_APP_SERVER_CODEX_COMMAND still wins when a specific local binary should be used.

For release readiness, inspect and replay stored events with bun run flow:backend show-event, show-run, and replay-event. Do not run a fabricated full openai/codex release lifecycle; the first full lifecycle test should happen on the next real upstream release.

Development Flow

Development happens on jojo at jojo.build. Codeberg is configured as a push mirror, and GitHub is kept for npm trusted publishing only.

See docs/development-flow.md for remotes, key setup, jojo CLI setup, mirroring, and the release procedure.

Publishing

The canonical development home for this monorepo is jojo.build/peezy-tech/codex-flows. Codeberg mirrors peezy-tech/codex-flows; the GitHub repository at peezy-tech/codex-flows exists for npm trusted publishing.

The public release train publishes:

• @peezy.tech/codex-flows from packages/codex-client
• @peezy.tech/flow-runtime from packages/flow-runtime
• @peezy.tech/flow-backend-convex from packages/flow-backend-convex

Before the first publish:

bun run release:check

Because newly added npm packages do not exist yet, bootstrap their first version with a human npm session, short-lived npm token, or npm trusted-publishing setup from the public repo checkout. The peezy.tech npm organization/scope must exist first, and the publishing account or token must have write access to that scope:

for package in packages/codex-client packages/flow-runtime packages/flow-backend-convex; do
  (cd "$package" && npm publish --access public)
done

If first-publishing through GitHub Actions, add a short-lived NPM_TOKEN secret to the npm-publish environment before dispatching the workflow. The workflow uses that token when present and otherwise falls back to npm trusted publishing. After the first publish succeeds and package-level trusted publishing is configured, remove the bootstrap token.

After the packages exist, configure npm trusted publishing for each public package:

• Packages: @peezy.tech/codex-flows, @peezy.tech/flow-runtime, @peezy.tech/flow-backend-convex
• Repository: peezy-tech/codex-flows
• Workflow: .github/workflows/publish-codex-flows.yml
• Environment: npm-publish

Future publishes should use the GitHub Actions workflow and should not require an npm token.

Packages

@peezy.tech/codex-flows

The low-level app-server client package. It exports:

• @peezy.tech/codex-flows: Node/Bun entry with stdio and WebSocket transports.
• @peezy.tech/codex-flows/browser: browser entry with WebSocket transport only.
• @peezy.tech/codex-flows/flows: framework-agnostic helpers for app servers that want to start Codex-backed workflows.
• @peezy.tech/codex-flows/workbench: transport-neutral thread UX state reducers and app-server request descriptors.
• @peezy.tech/codex-flows/rpc: JSON-RPC helpers and types.
• @peezy.tech/codex-flows/generated: generated Codex app-server protocol types.

@peezy.tech/codex-opencode-go-router

Private workspace package for running a local Responses API adapter that lets Codex use OpenCode Go chat-completions providers. It maps Codex Responses requests, tool specs, tool-call outputs, and DeepSeek reasoning replay to the OpenCode Go upstream surface. See packages/codex-opencode-go-router/README.md.

flow-runner

CLI package for listing flow packages, firing every step that matches a FlowEvent, or running one explicit flow step.

flow-backend-systemd-local

HTTP and CLI backend that persists dispatched flow events/runs to SQLite and starts matching steps locally. It is intended to run as a small systemd-managed service, with optional transient systemd-run units per step.

@peezy.tech/flow-runtime

Shared runtime package for loading flow.toml, validating payload JSON Schema, matching steps to generic events, and invoking Bun or feature-flagged Code Mode steps. It also exports @peezy.tech/flow-runtime/backend-client for backend-native flow event/run inspection and control over HTTP. That client normalizes backend-owned run state such as process status, semantic FLOW_RESULT status, attempts, output, replay, cancel, and attention flags.

Boundary

App-server thread commands stay app-server-native: consumers should call client.request(method, params) or the generated protocol methods directly. Workbench helpers derive UI state and return { method, params } descriptors; they do not execute app-server calls. Flow backend clients operate on generic FlowEvent, runs, attempts, output, replay, and cancel state. Domain completion such as pet-game asset registration, payment updates, or minting remains in the installing app's worker or Convex wrappers.

@peezy.tech/flow-backend-convex

Reusable Convex component package for generic flow event, run, attempt, lease, output, replay, cancel, and inspection state. Apps install its Convex component and expose their own authenticated wrappers for service workers.

web

The browser app imports @peezy.tech/codex-flows/browser, opens a direct WebSocket connection, lists threads, starts turns, interrupts running turns, and renders thread items and live app-server events.

cli

CLI package for piping JSON params into app-server JSON-RPC actions over a running WebSocket listener. It defaults to ws://127.0.0.1:3585, respects CODEX_WORKSPACE_APP_SERVER_WS_URL, supports --url, and lists available actions from the generated app-server action list.

@workspace/ui

Shared Tailwind/shadcn-compatible UI primitives used by the web app.