# 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:

```bash
bun install
```

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

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

Start the web app:

```bash
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:

```bash
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:

```bash
bun apps/cli/src/index.ts actions
```

## Build And Test

```bash
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](docs/flows.md) for `flow.toml`, generic
`FlowEvent` dispatch, Bun and Code Mode runners, the systemd-local backend, and
the Codex release flows.

```bash
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:

```bash
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](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:

```bash
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:

```bash
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/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.

### `@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.