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)"

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.

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.

@peezy.tech/codex-flows is published from packages/codex-client.

Before the first publish:

bun run --filter @peezy.tech/codex-flows release:check

Because the npm package does not exist yet, bootstrap the first version with a human npm session or short-lived npm token 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:

cd packages/codex-client
npm publish --access public

After the package exists, configure npm trusted publishing for:

• Package: @peezy.tech/codex-flows
• 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/rpc: JSON-RPC helpers and types.
• @peezy.tech/codex-flows/generated: generated Codex app-server protocol types.

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.

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.