165 lines
5.3 KiB
Markdown
165 lines
5.3 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)"
|
|
```
|
|
|
|
Code Mode flow steps are present on `main` but require
|
|
`CODEX_FLOWS_ENABLE_CODE_MODE=1` before execution.
|
|
|
|
## 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.
|
|
|
|
`@peezy.tech/codex-flows` is published from `packages/codex-client`.
|
|
|
|
Before the first publish:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|