Codex Web Reader

Codex Web Reader (cwr) is a lightweight, local, read-only web application for browsing saved Codex conversations. It starts Codex App Server as its data source and renders Markdown, LaTeX, highlighted code, tables, and collapsible tool calls in the browser.

Features

• Lists conversations by most recent update and opens the newest one automatically.
• Renders user and assistant messages with Markdown and KaTeX support.
• Keeps command, MCP, dynamic tool, and file-change details collapsible.
• Reads through codex app-server; it does not parse Codex databases or rollout files directly.
• Binds to 127.0.0.1 and exposes read-only HTTP endpoints.

Requirements

• Node.js 22 or newer
• Codex CLI 0.144.6, or a compatible version, available on PATH

Install

npm install -g codex-web-reader
cwr --version

To build an npm package from source instead:

git clone https://github.com/AuncelFan/codex-web-reader.git
cd codex-web-reader
pnpm install --frozen-lockfile
npm pack
npm install -g ./codex-web-reader-0.2.0.tgz
cwr --version

Building from source also requires pnpm 10. npm pack builds the application through its prepack hook. Installing the resulting tarball copies the package into npm's global node_modules; it does not link the command to the source checkout. Use the filename printed by npm pack when the version changes.

Usage

cwr             Start the service and open the browser
cwr --version   Print the version
cwr --help      Show help

By default, CWR listens on http://127.0.0.1:43127/ and runs until it receives Ctrl+C, SIGINT, or SIGTERM.

| Environment variable | Purpose | | --- | --- | | CWR_PORT | Override the HTTP port. | | CWR_NO_OPEN=1 | Do not open a browser, suitable for a service manager. | | CODEX_HOME | Select a non-default Codex data and configuration directory inherited by App Server. |

Run With systemd

Resolve the absolute paths to cwr and the directory containing codex before creating the unit:

command -v cwr
dirname "$(command -v codex)"

Create ~/.config/systemd/user/codex-web-reader.service and replace the example paths:

[Unit]
Description=Codex Web Reader
After=default.target

[Service]
Type=simple
Environment=CWR_PORT=39996
Environment=CWR_NO_OPEN=1
Environment=PATH=/absolute/path/to/node-and-codex/bin:/usr/local/bin:/usr/bin:/bin
# Set this only when Codex uses a non-default home directory.
# Environment=CODEX_HOME=/absolute/path/to/codex/home
ExecStart=/absolute/path/to/cwr
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target

Enable and manage the service:

systemctl --user daemon-reload
systemctl --user enable --now codex-web-reader
systemctl --user status codex-web-reader
journalctl --user -u codex-web-reader -f

Run loginctl enable-linger "$USER" if the user service must continue without an active login session. This may require administrator authorization.

Development

pnpm install --frozen-lockfile
pnpm typecheck
pnpm test:unit
pnpm build
node dist/cli.js

Publishing

Releases are published by GitHub Actions when a v* tag matching the version in package.json is pushed. Before creating its version commit and tag, npm version patch, npm version minor, or npm version major runs the local type checks, unit tests, and package dry run through the preversion hook.

Security

CWR only listens on the loopback interface, does not enable cross-origin access, and does not provide conversation mutation endpoints. Treat the selected CODEX_HOME as private data and do not expose the HTTP server through a public proxy.

License

MIT