206 lines
7.1 KiB
Markdown
206 lines
7.1 KiB
Markdown
# 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.
|