Skip to content
OzoneH3Public

About

Yet Another Codex Web UI

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Yacwu — Yet Another Coding Web UI

Note

This repository continues development of the original Yacwu by AFK-surf, with additional features and fixes. Credit to the original authors; their MIT license and copyright notice are preserved.

A workspace for Codex and Claude — a focused web front-end for Codex and, through an optional Claude adapter, Claude Code. Built with a Gleam (BEAM/OTP) backend and a Svelte SPA front-end.

Originally Yet Another Codex Web UI, Yacwu is now Yet Another Coding Web UI, bringing both providers into the same browser workspace.

It talks to Codex directly, and Claude through an adapter, over the app-server protocol (JSON-RPC 2.0 over stdio). Conversation history stays with the selected backend rather than in a Yacwu conversation database. Yacwu additionally keeps browser preferences and session rules locally, and records usage/diagnostic journals on the server.

Warning

Yacwu is built for one person on a trusted machine. Agents run without approval prompts and with full access to the account running Yacwu, so anything that can reach Yacwu can do whatever that account can. Signing in does not separate users: everyone signed in shares the same sessions and files. start.sh and the user service turn authentication off; keep Yacwu on 127.0.0.1 (the default) unless you configure authentication, and treat the OAuth login as convenience rather than hardened security (it reads who you are from the provider's userinfo endpoint; for a provider without one it falls back to ID-token claims it does not verify).

Features

  • 🖥️ Light and dark themes, responsive for desktop and mobile
  • 🔀 Codex, Claude and Copilot sessions side by side; pick the provider and project folder per session
  • 🧵 Multi-session workspace: create, rename, reorder, clear, archive, restore, and delete sessions, and resume interrupted work; Clear first in the message box starts that message in a fresh conversation, or clears without sending using Clear now
  • 🗂️ Move a session to another folder from Session details (type it or browse, as for new sessions); it applies with your next message (Claude sessions bring their conversation along)
  • ✅ Completion badges persist across tabs for finished sessions until you reopen them or start new work
  • 🔔 Soft sounds when a session finishes, asks a question, or hits an error; the speaker button at the top right mutes them, and resting on it opens a volume slider that previews each change
  • 🔒 In-use detection warns before opening a session another Codex process has loaded
  • Usage refreshes skip unchanged results, reuse a bounded host cache, and pause observations in hidden tabs; background recovery limits concurrent status requests.
  • 🪶 Background usage analysis reuses appended-event state and caches journals between reloads; cached session indicators and shared process snapshots keep long sessions responsive
  • Local Codex sessions open on recent turns, with older messages loaded on demand; history replays in a single pass without a duplicate transcript request during resume.
  • ⚡ Live streaming of messages, reasoning, commands, plans, and file changes; message timestamps survive browser refreshes; steer a running turn, stop it, or resume it later
  • 🧹 Compact activity folds older commands, MCP calls, file changes and agent updates into expandable groups. The latest activity stays visible while working, as does a final failure; Show all activity shows the full trace
  • ⏱️ Session bar with task progress, time-left estimates, elapsed time, and 5-hour / 7-day usage with reset countdowns; quota-stopped sessions keep a sidebar wait clock visible while allowance readings refresh, including after reload without opening those sessions
  • ⚡ A global Codex limit reset announced by OpenAI (from the public codex-resets.com API) shows next to the Codex usage until it lands, so the rest of the week's allowance can be used first (YACWU_RESET_FEED=off turns it off)
  • Codex Task allowance usage includes public reset reports, a history table, and an explicitly labelled estimate based on recent gaps; cached reports and personal account resets remain distinct.
  • 🧪 While such a reset is announced and nothing else runs, Yacwu samples unmeasured Codex model and thinking combinations, most costly first. Samples use short text workloads, advance after an interrupted attempt, and target one allowance point each (YACWU_RESET_BENCHMARK=off turns it off)
  • 💓 A running task's Current activity shows a running token count (estimated from streamed text until the backend reports one) and its latest sign of progress (thinking, writing, a step; its agents count too)
  • ⚙️ A running Claude session also lists the processes it runs on this machine (its busiest workers with their CPU use, or that none is running), so a quiet background worker can be told from a hang
  • 🤝 Multi-agent visibility: switch between a session and its spawned agents, with read-only agent transcripts
  • 🔒 File access for Codex and Claude: choose a default in Settings, override at creation or in Session details, and keep read-only access through resumes and forks
  • Session status dots show sign-in errors in red and offline backends in gray, with explanatory tooltips.
  • Claude allowance reserve is shared across sessions and browsers; changes apply to running-task checks and waiting resumes.
  • 🧠 Per-session model and reasoning effort that persist across server reloads, applied to new turns including session messages, with "Suggest settings" and capability/efficiency indicators in the picker, including provisional GPT-6.2 Sol and Astra ratings; a red ! marks sessions with a better rated model available under the same provider cost policy (see rating methodology) — restart running work on changed settings while preserving queued todos
  • Background checks share runtime reads across tabs and build checks across connections; usage refreshes coalesce and idle calibration polling backs off and pauses in hidden tabs
  • Codex cost estimates normalize older eligible Pro/Business Premium samples for the reported 29 October allowance doubling; raw readings stay unchanged and intervals crossing the announcement cutoff are excluded.
  • 💸 Learned allowance cost per model and thinking level, projected task cost while work runs, and a task usage history with manual benchmarks
  • 💬 Interactive answers: questions and action requests dock below the transcript, without blocking it, and queue per session, including requests from agents
  • 📁 Workspace browser with a Monaco editor, file previews, and clickable file links in responses
  • ± Git changes inspector with All / Staged / Unstaged scopes and lazy diffs
  • 🖼️ Attach images, PDFs, and text/code files (including .txt) by picker or clipboard paste; click to open, or × to remove
  • 🧭 Transcript position rail and scroll-to-bottom control; recover a missed final response from saved history when a task finishes
  • 📋 Copy files collects the contents of every file a response links to; Copy for coordinator copies a Markdown handoff (session, folder, branch, request, response, changed files and linked file contents) for another chat; Copy full result does the same for every response since the last prompt and shows a green check once copied, until the task changes
  • ⌨️ Slash commands (see below), message copy buttons, and prompt history
  • 📐 Project rules: one rule set per repository, shared by all its worktrees and by Codex and Claude sessions alike, given to each new session at start; Session details shows which version a session started with and flags outdated ones
  • 📝 Per-session rules: progress reporting, shared coordination, and custom instructions. Shared coordination gives agents the session name and lets same-folder Codex and Claude sessions leave notes in .workspace/coordination
  • 📂 Agents are told to write only inside the session folder, keeping scratch and temporary files in its self-ignoring .workspace/
  • 📨 Session messages: agents in Codex and Claude sessions on this machine can message each other; a working recipient gets them at its next input boundary (including after a server reconnect), an idle one with its next prompt, a Send now button, or automatically with the auto-send setting; messages blocked by Claude's allowance stay queued (see docs/relay.md)
  • ⚙️ Settings menu (sidebar gear) for browser-wide preferences: theme, Enter to send, activity view, output collapsing, session rule defaults, Claude progress reminders and time-left correction, Claude allowance lockout %, quiet-worker notices, and whether sessions accept direct messages
  • 🎛️ Per-session Codex profiles from $CODEX_HOME/<name>.config.toml
  • 🧾 /todo <task> queues follow-up work to run after the current turn
  • Persistent backend output uses bounded buffering and backpressure; excess queued requests receive an explicit error.
  • ♻️ Optional persistent backends (YACWU_PERSISTENT_BACKENDS=1): restarting Yacwu leaves running agents alone
  • 🩹 Tasks cut off by a crashed backend (or Yacwu itself) continue on their own once it is back, at most twice per half hour per session
  • 🏷️ The session list footer shows the build's commit and offers a reload when a newer build is deployed
  • 🔁 Alternative backends via YACWU_BACKENDS, such as claude-codex
  • 🐙 GitHub Copilot sessions through Copilot CLI's ACP server, with priced model choices and estimated credits per task
  • 🛑 Optional server-enforced stops: Codex at a remaining-allowance percentage, Copilot at a billing-cycle credit total (both off by default)
  • 🔑 Password-assisted SSH setup creates a dedicated key for 1 hour to 7 days, with host fingerprint confirmation and access revocation.
  • 🌐 Remote machines over SSH with a persistent app-server and full feature parity (see docs/remote.md)
  • 🗄️ No storage layer — the backend is the source of truth

Codex and Claude

Codex is the default backend. Enable the optional claude-codex adapter to add Claude to the new-session Provider picker; both providers' sessions then appear in the same sidebar. The file browser, diffs, session rules, prompt queue and transcript controls remain part of the shared Yacwu interface.

Claude model names are discovered from its SDK and account catalog rather than hard-coded. Where available, its 5-hour and weekly allowance windows appear in the Session bar. Task history records tokens and runtime, and learns allowance costs separately for each provider/model/thinking combination. Missing readings or insufficient calibration are shown as unavailable or still learning, not treated as zero consumption. If the usage endpoint is temporarily rate-limited, Yacwu rechecks after its retry time; rejected prompts are never silently queued.

Claude support is adapter-based, not a native Anthropic app-server integration. Agent events, approvals, steering and backend-specific slash commands depend on what the adapter exposes; identical behavior across providers is not guaranteed. Switching a GPT conversation to Claude in place is not supported: create a separate session for the other provider instead. Sessions in the same project folder can use shared coordination notes and direct session messages, but do not share conversation history.

Slash commands

Type these in the composer (anything not starting with / is a normal model turn):

command action
/status show account, rate limits & session info
/model show the current model, reasoning effort, and available choices
/model <model> [effort] change the model and optional reasoning effort (--effort <effort> changes effort only)
/profile show the session's codex profile and the available choices
/profile <name> / /profile clear switch this session to a profile / back to the base config
/mode show the current file access mode (read-only or read-write); autocomplete offers /mode rw in read-only sessions
/mode r / /mode rw set read-only or read-write file access (changes apply to the next turn)
/goal <objective> set the thread goal (--budget N to add a token budget)
/goal / /goal clear show / clear the current goal
/todo <task> queue a follow-up task with any attached files or images; saved across refreshes to start after the current task
/todo show queued tasks and their status
/todo clear clear queued tasks that have not started
/todo rm <number> remove a pending task by its /todo list number; typing /todo rm lists the tasks to pick from, with started and finished ones marked (they cannot be removed)
/compact compact conversation history
/review [notes] review uncommitted changes (or run a custom review)
/shell <command> run a user-initiated shell command in the thread
/rollback [turns] roll back the last N turns (default 1)
/fork [provider] branch this thread, optionally switching to an enabled provider
/btw [question] ask on the side: a throwaway fork with the message box focused and a Close button beside its parent link, nested under its parent and deleted when closed, told to treat the history as reference and not to change anything (an instruction, not enforced)
/archive archive this session
/help list the commands

Windows support

Yacwu includes native Windows foreground startup for local Codex only. Windows startup has been confirmed by a user; the full native acceptance checklist remains pending. The implementation has been checked on Linux and has a Windows CI job. See the conversion status and acceptance checklist.

Install the build toolchain from PowerShell in this checkout:

.\install-windows.ps1
# Preview installation and PATH changes:
.\install-windows.ps1 -WhatIf

The installer uses WinGet for Node.js LTS (24+), Git, Bun 1.3+, Gleam 1.18+, and Erlang/OTP 27+, skips compatible versions, and installs checksum-verified rebar3 3.27.0 into .workspace/tools/rebar3 if needed. It adds missing tool directories to your user PATH. Reopen PowerShell afterward. Erlang installation may show a Windows elevation prompt. If WinGet is missing, install Microsoft App Installer first. If you move this checkout, rerun the installer to update the rebar3 PATH entry.

The package IDs come from the WinGet manifests; the rebar3 wrapper follows its Windows installation instructions.

After reopening PowerShell, install Codex if needed and authenticate it:

npm.cmd install -g @openai/codex
codex login
.\start.ps1
# Optional server arguments:
.\start.ps1 --port 3001

If your PowerShell execution policy blocks the script, invoke it for this process with powershell -NoProfile -ExecutionPolicy Bypass -File .\start.ps1 (or use install-windows.ps1 as the file for prerequisite installation). The launcher builds the application and starts it on 127.0.0.1:3000, with authentication disabled by default for local use. HOST, PORT, YACWU_INSECURE_SKIP_AUTH, and other server overrides remain available. After building, bun run start uses the portable Node launcher; it retains the server's normal authentication requirement unless configured explicitly.

Codex runs over stdio. YACWU_CODEX_BIN optionally identifies a native codex.exe; standard global and local npm Codex installations are resolved automatically. Stopping the foreground server stops its Codex process tree. Existing bounded task recovery may resume interrupted work after restart. Windows does not enable persistent daemons, SSH hosts, Claude/Copilot, or external session in-use detection.

Windows state defaults to %LOCALAPPDATA%\yacwu; XDG_STATE_HOME overrides the parent directory. Codex keeps its existing %USERPROFILE%\.codex home (or CODEX_HOME). Uploads use TMPDIR, TEMP, or TMP. Relay credentials are protected with a current-user ACL using Windows PowerShell.

Read-only sessions retain Codex sandbox restrictions. Configure the native Windows sandbox before using them; sandbox errors do not cause a fallback to full access.

Requirements

  • Gleam ≥ 1.18 with Erlang/OTP ≥ 27 (and rebar3 on PATH for compiling one transitive Erlang dependency) — .tool-versions pins the versions for asdf users
  • Bun ≥ 1.3 (builds the web UI)
  • codex CLI on PATH, already authenticated (codex login)
  • Node.js ≥ 24 (portable server launcher and session relay)
  • Optional Claude support: a built claude-codex checkout and working Claude authentication. See adapter setup.

Run

bun install
bun run build                              # build the web UI into ./build
YACWU_INSECURE_SKIP_AUTH=1 bun run start   # serve UI + API on http://127.0.0.1:3000

./start.sh installs dependencies and builds the UI and the server. With the yacwu user service installed it then restarts the service on that build, leaving running agents alone; otherwise (or with ./start.sh --foreground) it runs the server in the foreground. The foreground run defaults to authentication disabled for local use, the Claude backend below, and persistent backends. Environment overrides are respected; use YACWU_BACKENDS= ./start.sh --foreground for Codex only.

bun run start runs the Gleam server (server/), which serves the static UI build, the REST/SSE API, and spawns/manages one codex app-server process (plus one per configured alternative backend). The server fails closed: it refuses to start unless authentication is configured (see Authentication) or YACWU_INSECURE_SKIP_AUTH=1 explicitly opts into running open, as above for a localhost-only setup. The listening address is configurable:

cd server
gleam run -- 0.0.0.0:8080            # positional host:port
gleam run -- --host 0.0.0.0 --port 8080
gleam run -- --unix /run/yacwu.sock  # Unix domain socket instead of TCP
gleam run -- --help

The server accepts -H/--host, -p/--port, a positional host:port, or --unix <path> (CLI flags override the HOST/PORT env vars). YACWU_CWD selects the working directory for new sessions; YACWU_STATIC points at the web UI build directory (default ./build, relative to where the server runs — the bun run scripts set it for you). Set YACWU_DEBUG=1 for a per-request timing log on stderr.

Restarting without stopping agents

By default the local codex app-server and each alternative backend run as children of the server, so restarting Yacwu interrupts their running turns (Yacwu offers to continue them afterwards). With YACWU_PERSISTENT_BACKENDS=1 they run as detached daemons on Unix sockets in ~/.cache/yacwu/ instead, started by the same bootstrap remote hosts use: restarting Yacwu reconnects to them and their turns keep running. Stdio backends such as the Claude wrapper run inside scripts/backend-daemon.mjs.

YACWU_PERSISTENT_BACKENDS=1 ./start.sh

To run Yacwu itself as a systemd user service, run scripts/install-service.sh from a shell where bun run start works (the service keeps that shell's PATH), then systemctl --user enable --now yacwu. Local daemons start in systemd scopes of their own, so systemctl --user restart yacwu restarts only the server. Extra environment goes in ~/.config/yacwu/service.env.

Daemons keep the code and environment they started with. After updating codex, the Claude wrapper or the adapter, stop them so the next request starts fresh ones: pkill -f "app-server --listen unix://$HOME/.cache/yacwu/". After a restart Yacwu resumes the threads the daemons are still running, so their events keep streaming, and open pages reload what they missed while it was down. Backends run by backend-daemon.mjs (such as the Claude wrapper) also hold the events and requests they send meanwhile and deliver them on reconnect, so an agent's question is not lost; that needs a daemon started by this version.

Alternative backends

Claude sessions stay active while SDK background workers or explicitly finite monitors run. Current activity shows “Background worker running”; when the tracked work ends, Yacwu silently asks Claude to check the results and report status before completing the turn. Opaque detached commands require a finite Monitor; persistent ambient watchers do not keep a session running. A turn also ends once Claude Code reports itself idle, so a finished task cannot stay marked as running.

Anything that speaks the codex app-server protocol over stdio can stand in for codex app-server — for example claude-codex, which serves the protocol backed by Claude Code. Declare such backends with YACWU_BACKENDS, semicolon-separated name=command entries:

Prepare the optional adapter checkout before enabling Claude (Node.js is also required). It is managed separately and ignored by this repository:

git clone https://github.com/fuergaosi233/claude-codex.git
cd claude-codex
bun install
bun run build
cd ..
YACWU_BACKENDS="claude=node ./scripts/claude-backend.mjs ./claude-codex/dist/src/adapter.mjs" bun run start

The Claude wrapper supplies the 5-hour and 7-day subscription allowance using Claude Code's local login (~/.claude/.credentials.json, or under CLAUDE_CONFIG_DIR). It also accepts CLAUDE_CODE_OAUTH_TOKEN. Account reads are cached for five minutes when comfortably above the reserve, two minutes near it, and back off progressively when rate limited; unavailable subscription data leaves the allowance windows hidden. Model discovery merges the CLI's aliases with concrete model IDs returned by the signed-in account's Models API. This lets newly available models appear even when the Agent SDK's bundled CLI catalog predates their release. If the account catalog cannot be read, discovery falls back to the CLI list. Claude task allowance uses the same observed weekly-quota calibration as Codex, with separate rates for each model and thinking level. Cache-read tokens are normalized for both live reports and older recordings. Task estimates and projections appear once sufficient clean observations exist; until then the UI shows that costs are still being learned. Claude's token usage is reported after each model response, so a running Claude task shows its allowance used so far and a projection; before the first report it shows "Cost pending" when its model and thinking level have a rate. Model IDs the catalog lacks (claude-opus-5-5 next to its opus alias) learn under the same name as the alias, so each model keeps one rate. When available, 5-hour readings are also recorded and calibrated separately from the weekly allowance. Task usage history lets you select either window; task totals, projections, and thinking-cost labels show each learned estimate. Percentages from the two windows are never combined or converted using their durations. Older quota records remain weekly-only, and resets invalidate observations spanning that reset for the affected window.

Claude appears under Provider in the new-session form when configured, alongside Codex. Machine selects this computer or an SSH remote; Claude currently runs on this computer. Creation uses the provider's default model, which can be changed afterwards in the composer. Each backend runs its command as a child process on this machine — same working directory, file browser, Git viewer, profiles and in-use detection as the default. Sessions started on a backend are listed and resumed through that backend, and merge into the session rail with everyone else's. The command is split on whitespace (no quoting) and resolved via /usr/bin/env, so bare program names use PATH and absolute paths work as-is. Names must be URL-safe (letters, digits, .-_@) and may not be local; a backend name shadows an identical ~/.ssh/config alias.

Relative script paths resolve from the Yacwu project folder when using bun run start or bun run dev:server. For other launchers, set YACWU_BACKEND_ROOT to an absolute base directory; otherwise the launch environment's PWD is used. Backend session working directories remain independent of this script path.

Claude model catalogs hide the adapter's GPT/Codex proxy choices in the model picker, suggestions and benchmark selection. Use a regular Codex session for GPT models; Claude sessions keep their Claude choices.

The Claude launcher discovers the installed Agent SDK's supported models on backend startup without submitting a prompt. It labels aliases with their resolved versions (rather than hard-coding model releases), and disables the adapter's Codex proxy.

For Claude turns, the launcher synchronizes the adapter's model/runtime settings before forwarding the prompt. This also fixes older adapter sessions that retained a Codex runtime despite selecting a Claude model. If synchronization fails, the prompt is not started; it is never silently sent to the GPT runtime instead.

Discovery failures fall back to the adapter's aliases; an explicit CLAUDE_CODEX_MODELS configuration is respected. The adapter must be built with its SDK dependency installed before launching. You can still invoke the adapter directly if you do not want discovery.

Claude sessions have a Claude usage shortcut to recorded task token counts and runtime. Session details show the live reported total, input, cached-input and output counters when received. These live counters may reset on adapter restart; recorded task history is separate. The adapter does not supply Claude account allowance percentages, so these are not equivalent to its subscription usage meter.

Navigating into a folder in the new-session directory browser selects that folder as the working directory, including for local Claude backends. You do not need a second confirmation click before starting the session.

GitHub Copilot

GitHub Copilot CLI runs as a backend through its Agent Client Protocol server (copilot --acp, a public preview). The Copilot launcher reuses the claude-codex adapter for sessions and history, with Copilot doing the work:

npm install -g @github/copilot && copilot login
YACWU_BACKENDS="claude=…;copilot=node ./scripts/copilot-backend.mjs ./claude-codex/dist/src/adapter.mjs" bun run start

Copilot then appears under Provider next to Codex and Claude, on this computer. Sessions keep their Copilot conversation across restarts and folder changes; if Copilot cannot reopen it, Yacwu reports an error rather than starting a replacement. Commands, edits, reads, plans and token counts show as in other sessions, and the token meter follows Copilot's live context use. Full-access sessions turn on Copilot's allow-all; others ask before each tool. A message sent while Copilot works is queued as the next prompt of the same task, since ACP cannot add input to a running prompt.

Models. The picker lists the models the account may use, grouped by maker, each with its own thinking levels (from "none" to "max") and its cost multiplier in the name ("Claude Opus 5.5 · 15x"). The list is read once a day from an empty session, without a prompt. New sessions start on GPT-6 Luna; Copilot's Auto is not offered. A model is hidden only when another of the same maker is at least as capable and costs no more at Copilot's fixed AI-credit prices; models without a known price stay visible. Older GPT models are hidden when a GPT-6 one is offered. The list is sorted by input price, then capability.

Credits. Each task shows an estimate of the credits it used, from the token counts and those fixed prices (a range where cache pricing is uncertain), with a credit history view. If gh is signed in on the backend host, Yacwu also reads the account's credits used this billing cycle from GitHub's internal Copilot endpoint, cached for five minutes. That endpoint is undocumented and can change. The reading names the GitHub CLI login, which may differ from the Copilot CLI login. It shows any finite allowance, or says that no cap was reported (organization budgets may still apply). Without a reading, no account figure is shown. The optional Copilot credit stop in Settings uses this reading.

Not available: an allowance reading through ACP itself, and forks with the earlier conversation: /fork and /btw start a fresh Copilot conversation. Session records live in $XDG_STATE_HOME/yacwu/copilot-adapter; deleting an archived session also removes Copilot's copy. YACWU_COPILOT_CLI selects another copilot binary.

For a deployable artifact, cd server && gleam export erlang-shipment produces a self-contained BEAM release (needs only Erlang on the target), and bun run build supplies the static build/ directory to serve next to it.

Release tarball

./scripts/build-release.sh    # produces dist/yacwu-<version>.tar.gz

Uses the local toolchain (no Docker): the backend becomes a single-file escript (gleam export escript) bundled with the web UI build and a yacwu launcher. The result is portable BEAM bytecode — the target machine needs a compatible Erlang/OTP (≥ the version pinned in .tool-versions) and the codex CLI, but no Gleam or Bun:

tar -xzf yacwu-1.0.0.tar.gz
./yacwu/yacwu 0.0.0.0:8080

AppImage

./scripts/build-appimage.sh   # produces dist/yacwu-<architecture>.AppImage

Requires Docker (or podman with the docker CLI shim). The whole build runs in an Ubuntu 20.04 (glibc 2.31) container so the resulting AppImage works on distros at least that old: it pulls the prebuilt Erlang/OTP for that distro from hex.pm's build service (the same builds erlef/setup-beam uses), exports the backend with gleam export erlang-shipment, and bundles the Erlang runtime, the web UI build, and the non-glibc shared libraries the runtime needs (libssl, libtinfo, …). Both x86_64 and aarch64 Docker hosts are supported; the output uses the corresponding architecture in its filename.

./dist/yacwu-$(uname -m).AppImage --help
./dist/yacwu-$(uname -m).AppImage 0.0.0.0:8080

The AppImage accepts the same flags/env as the server. It still needs the codex CLI on PATH at runtime (and libfuse2, like any AppImage — or run it with --appimage-extract-and-run).

Develop

bun install
YACWU_INSECURE_SKIP_AUTH=1 bun run dev:server
                     # Gleam API backend on http://127.0.0.1:3000
bun run dev          # Vite dev server on http://127.0.0.1:5173 (proxies /api)

The front-end dev server proxies /api/* (including the SSE stream) to the backend, so edit Svelte code with hot reload while the Gleam server runs unchanged. Set YACWU_API to proxy to a backend on a different address.

Authentication

Two mechanisms, usable separately or together. The server fails closed: with neither configured it refuses to start (and rejects every request with 403) unless YACWU_INSECURE_SKIP_AUTH=1 explicitly opts into running without authentication — only do that on a trusted network, e.g. bound to localhost.

Forward auth

Put yacwu behind a reverse proxy that authenticates users and injects a Remote-User header (Authelia, Traefik forward-auth, oauth2-proxy, …). Pass an allowlist to require that header:

cd server
gleam run -- --remote-user alice,bob  # or: YACWU_REMOTE_USERS=alice,bob

When enabled, every request must carry Remote-User: <user> matching one of the listed users — otherwise it's rejected (401 if the header is missing, 403 if the user isn't allowed). This is enforced for pages, the API, and static assets. When unset, forward auth is disabled.

Built-in OAuth login

yacwu can also authenticate users itself against an OAuth 2.0 / OpenID Connect provider (authorization code flow with PKCE), so no authenticating proxy is needed:

cd server
YACWU_OAUTH_ISSUER=https://auth.example.com \
YACWU_OAUTH_CLIENT_ID=yacwu \
YACWU_OAUTH_CLIENT_SECRET=... \
YACWU_OAUTH_USERS=alice,bob \
gleam run

Register https://<your-yacwu-host>/oauth/callback as the redirect URI with the provider. Unauthenticated page loads bounce to the provider's login page; after the callback the user stays signed in via an HMAC-signed yacwu_session cookie — stateless, like everything else in the server. API requests without a valid session get a plain 401. /oauth/logout signs out.

variable meaning
YACWU_OAUTH_ISSUER OIDC issuer; endpoints found via /.well-known/openid-configuration
YACWU_OAUTH_AUTH_URL / YACWU_OAUTH_TOKEN_URL explicit endpoints (override discovery; both required when no issuer is set)
YACWU_OAUTH_USERINFO_URL userinfo endpoint: where Yacwu reads who logged in (the id_token is used only without one)
YACWU_OAUTH_CLIENT_ID / YACWU_OAUTH_CLIENT_SECRET client credentials registered with the provider
YACWU_OAUTH_SCOPES requested scopes (default openid profile email)
YACWU_OAUTH_USER_CLAIM claim holding the user identity (default: first of preferred_username, email, login, sub)
YACWU_OAUTH_USERS comma-separated identity allowlist; empty admits any authenticated user
YACWU_OAUTH_REDIRECT_URL explicit callback URL, when the one derived from X-Forwarded-Proto / X-Forwarded-Host / Host is wrong
YACWU_OAUTH_COOKIE_SECRET cookie-signing secret; auto-generated per process when unset (sessions then survive only until a restart)
YACWU_OAUTH_SESSION_TTL session lifetime in seconds (default 604800, 7 days)

Plain OAuth 2.0 providers without OIDC work via explicit endpoints — GitHub, for example:

YACWU_OAUTH_AUTH_URL=https://github.com/login/oauth/authorize \
YACWU_OAUTH_TOKEN_URL=https://github.com/login/oauth/access_token \
YACWU_OAUTH_USERINFO_URL=https://api.github.com/user \
YACWU_OAUTH_SCOPES=read:user \
YACWU_OAUTH_CLIENT_ID=... YACWU_OAUTH_CLIENT_SECRET=... \
YACWU_OAUTH_USERS=octocat \
gleam run

When both mechanisms are configured, a valid Remote-User header or a valid session cookie admits the request; anything else is sent through the OAuth login.

Other commands

bun run check        # svelte-check / TypeScript (front-end)
bun run test:unit    # front-end unit tests (bun test)
bun run test:server  # backend unit tests (gleeunit)
bun run test:adapter # Claude adapter and launch-path tests (skipped without the built claude-codex checkout)
bunx playwright test # end-to-end verification (builds the UI, runs the Gleam server, drives the live app)

Test servers use a separate temporary usage directory so their collector startup events do not invalidate live task recordings or calibration. They also get their own empty Codex home and Yacwu state, so tests never see your sessions or credentials and cannot spend a model turn: model replies are stubbed in the tests.

CI also runs the browser and adapter suites with isolated state, mock model responses, and a pinned adapter checkout.

Architecture

browser ──HTTP/SSE──> Gleam server (mist, server/)
                         │  server/src/yacwu/codex.gleam  (JSON-RPC manager actor)
                         └──stdio──> codex app-server ──> Codex sessions on disk
  • server/src/yacwu/codex.gleam — OTP actor owning the single codex app-server port: correlates request/response ids, broadcasts notifications to SSE subscribers, respawns the process if it exits.
  • server/src/yacwu/router.gleam — thin REST/SSE endpoints over the protocol (/api/threads, /api/threads/[id]/open|message|interrupt, /api/events), plus static serving of the built SPA with an index.html fallback.
  • server/src/yacwu/oauth.gleam — the built-in OAuth/OIDC login: endpoint discovery, PKCE, the code-for-token exchange, and the signed session cookies backing it (no server-side session storage).
  • server/src/yacwu/session_lock.gleam — detects whether another codex process has a session's rollout file open before we resume it.
  • server/src/yacwu/model_state.gleam — per-thread model/effort overrides and the model catalog.
  • server/src/yacwu/relay.gleam, relay_core.gleam — session messages: a pure delivery state machine and the actor that runs it (see docs/relay.md).
  • src/routes/+layout.svelte — the terminal-style UI; routes streamed events to the right session by threadId.

The backend is pure Gleam: interop with the VM (spawning the codex port, /proc symlink reads, Unix sockets) goes through typed @external bindings to Erlang built-ins — no Erlang source files, no NIFs.

Sessions default to read/write access (approvalPolicy: "never", sandbox: "danger-full-access"). Settings can select read-only for new sessions; creation and Session details can override it. Existing sessions keep their access choice, which is stored on the server and can change while idle.

Codex read-only sessions use its filesystem sandbox for commands and edits, deny permission escalation, and disable shell shortcuts and browser editor saves. Resumes, forks, spawned agents and cleared-session replacements retain the restriction. Connected external services retain their own permissions. Claude read-only sessions expose only Read, Glob, Grep and interactive questions. Commands, edits, subagents, workflows, skills and external tools are disabled; permissions and tool hooks enforce the same limit even when resuming a writable conversation. This is a restricted tool mode, while Codex uses its filesystem sandbox. SDK session bookkeeping can still write its own state.

The Claude backend must advertise the updated read-only guard before Yacwu allows the mode. After updating, finish ongoing Claude work and restart its persistent daemon to load the guard, then reload the browser. A Yacwu service restart alone does not update persistent backends. Copilot currently supports read/write access only.

Per-session profiles

codex profiles are $CODEX_HOME/<name>.config.toml files layered over the base config — but codex only applies them via the --profile CLI flag, which doesn't work with codex app-server, and the app-server protocol has no profile parameter. yacwu emulates the layering per-thread: the chosen profile file is parsed and passed as the generic config override map on thread/start / thread/resume (plus the profile's model/effort on turn/start). Explicit request params beat that map, so yacwu's forced approvalPolicy: "never" survives any profile, and an explicit /model override wins over the profile's model.

Profile files are re-read from disk on every request — nothing is cached, so edits take effect immediately. Which profile a session uses is remembered in-memory; after a server restart it is re-inferred as the profile whose model matches the session's current model, if any.

In-use detection

codex keeps an open file descriptor on a session's rollout .jsonl for as long as the thread is loaded (resumed) — even while idle. Before resuming, the open endpoint checks whether any process (outside our own app-server's process tree) holds that path open; if one exists it returns 409 and the UI shows a warning with the offending process so you can cancel or "open anyway".

The scan is platform-specific: on Linux it reads /proc/*/fd symlinks; on OpenBSD (which has no /proc) it runs fstat(1) on the rollout file and ps for the process tree. Other platforms degrade to no detection rather than blocking.

Unix socket listening

--unix <path> accepts connections on a Unix domain socket and relays them byte-for-byte to the HTTP listener bound on a loopback ephemeral port (mist itself only speaks TCP). HTTP, SSE, and auth headers/cookies pass through unchanged.

Stalled-task diagnostics

Yacwu records Codex RPC timing, lifecycle event metadata, connection changes, and browser Stop/SSE observations automatically. Every 30 seconds it records a manager snapshot with pending request ages, active turn activity, subscriber count, and the local Codex process ID. On Linux, snapshots also include process state, CPU counters, thread count, and resident memory pages. Quiet-turn warnings use the turn's starting thinking level: None/Minimal/Low 2 minutes, Medium 4, High 6, XHigh 10, Max 15, and Ultra 20 (unknown defaults to 4). Confirmed running commands, MCP calls and agent waits get at least 10 minutes. Warnings produce a turn_silent snapshot, repeated at most once every two minutes. Silence can also mean legitimate reasoning or a long-running tool; Yacwu does not cancel the turn automatically. The waiting/status/stop prompt closes automatically when that worker reports new activity or its turn ends.

Account polling is shared per backend: allowance reads are cached for at least two minutes, account identity for fifteen minutes, and concurrent reads share one pending request. Browser allowance requests time out after eight seconds and retain the last displayed values. A percentage remains visible when its reset timestamp is unavailable. While an allowance is depleted or below Claude's reserve and its reset time is known, checks slow to once every fifteen minutes, with a fresh check after reset.

With progress reporting enabled, Claude receives a silent reminder after five minutes without an estimate, only if other task activity occurred in those five minutes. Reminders are sent at most once every five minutes and are hidden from the transcript, including after reload.

Claude work is stopped and new tasks are blocked when either the five-hour or seven-day allowance reaches the configured reserve (10% remaining by default). Automatic stops appear in the transcript with the allowance reason and a Resume action, and queued todos stay paused.

  • Cancel automatic continuation beside a stopped Claude task’s Resume button to keep it paused; Resume remains available for a manual restart.

  • Claude session-limit refusals automatically continue after reset; recover existing stopped sessions with node scripts/claude-quota-recovery.mjs .workspace/QUEUE.json.

Allowance-stopped Claude tasks automatically continue after fresh readings show both windows above their reserve. Pending resumes survive restarts in .workspace; manual stops, archived sessions, and tasks superseded by another turn are not resumed. The transcript records the automatic resumption. After reset, unavailable usage retries after two minutes (or the endpoint's retry delay); unanswered history checks retry after thirty seconds. Sessions waiting for Claude's reserve or a depleted Codex allowance show a clock with the reset time when available. If both readings are unavailable, new tasks remain blocked until the allowance can be verified. Claude usage is checked before each new task. Recent valid readings are reused for five minutes when comfortably above the reserve, or two minutes near it; unknown readings and elapsed reset windows trigger a refresh. If the usage endpoint is rate limited, its retry delay is respected and displayed when starts cannot be verified. When refresh fails, a last verified reading safely above the configured remaining reserve remains usable; unknown or reserve-level readings still block new work. Repeated forced checks after a failed read are throttled to one attempt every two minutes; repeated rate limits increase the backoff and the endpoint's retry delay takes precedence.

Configured Codex and Copilot account limits retain the last verified usage reading through refresh errors for up to five minutes from that reading. Missing or older readings still block work; a refresh error never extends this deadline.

Logs live in $XDG_STATE_HOME/yacwu/diagnostics (default ~/.local/state/yacwu/diagnostics). Set YACWU_DIAGNOSTICS_DIR to override it. Each host has a codex-*.jsonl metadata log and a codex-*.stderr.log log. Metadata rotates at 5 MiB; local child stderr is checked every 30 seconds and retains the last 5 MiB in .1 before truncating in place. Each log keeps one previous file. The directory is mode 0700 and files are mode 0600. Log write failures do not prevent requests from running.

The metadata log excludes prompts, command output, and streamed text. The local Codex child's stderr is retained separately and can contain Codex's own error details. RUST_LOG defaults to info for newly spawned local children and respects an existing override. Remote Codex stderr stays on the remote host; local connection/RPC diagnostics are still recorded.

Yacwu also checks saved running tasks against backend runtime state every 15 seconds and on reconnect. Loaded-but-idle interrupted tasks (including Claude tasks interrupted by adapter restarts) stop their activity timer and show a recovery action and log the backend's interruption reason (or explicitly state that no reason was reported). Failed reads retain the current state; silence alone never stops a task that is still reported active.

To inspect a stalled session without waiting for a Codex RPC, read GET /api/threads/<session-id>/diagnostics (add ?host=<host> for remote routing). This uses the same authentication as the other API endpoints and returns the manager snapshot and exact log paths. Correlate its turn and request IDs with the retained logs and Codex's session transcript. It can separate an unresponsive RPC, disconnected transport, missing browser events, and a silent turn, but cannot guarantee an explanation for an internal model or upstream service stall.

Backend diagnostics take effect after restarting Yacwu; local stderr capture starts with the next local child. Let active tasks finish before restarting a server that owns their Codex child. Reload the browser after rebuilding.

Task allowance analysis

Spawn receipts provide evidence of new agent counters and their initial model/thinking settings, even if they arrive after the first turn. A matching first total and last token reading can also establish a fresh counter. Read/resume requests and their runtime replies are correlated automatically: stored counters from confirmed idle reads establish initial baselines without invalidating usage from other sessions. Active or failed reads, intervening turn activity, and unexplained positive deltas remain incomplete; stale stored snapshots cannot rewind a newer baseline. Existing-session totals remain cumulative; connection gaps remain partial.

For older local recordings, bun scripts/recover-usage.ts previews repairs using exact turn contexts, first-agent token readings, and completed-turn snapshots from saved Codex rollouts. Add --apply to append verified metadata without replacing the original history. Use --since <ISO-date> to limit the period, --usage-dir <path> for another usage directory, or --codex-home <path> for another local Codex home. Recovery excludes prompts and responses and can be rerun without duplicating repairs. Remote histories are not repaired by this local utility.

Usage metadata is stored per host in $XDG_STATE_HOME/yacwu/usage (default ~/.local/state/yacwu/usage); YACWU_USAGE_DIR overrides the directory. Files are private, rotate at 20 MiB, and retain one previous file. Prompts, responses, and tool output are excluded. Recording begins when the updated backend starts and continues without an open browser. Quota snapshots are sampled every 30 seconds and at turn boundaries, along with live quota/token notifications.

The history window separates the account-wide weekly percentage change from a task's estimated cost. Each row is one Codex turn; agents have separate rows. Token counts use differences in cumulative usage, including cached input, rather than the context-size counter. Existing turns without a known token baseline, or turns interrupted by a recording gap, are marked partial.

Calibration pools readings until at least two percentage points are consumed and token activity has been quiet for 60 seconds. Post-task readings allow a settling period for delayed quota updates. It learns nonnegative weights for uncached input, cached input, and output when independently identifiable; reasoning is counted within output once. Insufficient or indistinguishable token breakdowns use a labeled total-token fallback. Multiple independent observations are required for fitted weights. Before that, clean single-setting windows provide provisional total-token rates with explicit rounding ranges; they do not invent costs from mixed-only evidence or extrapolate cached-heavy samples to substantially different token mixes. Whole-percent differences are treated as ranges (up to one percentage point either side), and displayed uncertainty combines rounding and fit variation. The ranges are indicative, not guaranteed bounds.

Hosts with matching hashed account fingerprints share token evidence, using the selected host as the single quota source to avoid double-counting readings. An account ID is preferred when exposed; otherwise the fingerprint uses email, account type, and plan. Raw email addresses are not stored. Unidentified hosts remain separate; legacy host-only history remains available. Account, quota bucket and plan changes keep calibration separate. Quota resets, recording gaps and allowance changes without tracked tokens do not train the model. Elapsed time is recorded for comparison; waiting on a tool does not imply token consumption. Usage outside Yacwu can still affect shared allowance, so task costs remain empirical estimates. Static model value ratings are unchanged.

The usage window includes a Manual calibration benchmark runner. Choose a model, supported thinking level, weekly percentage-point target (2–5), maximum turns (1–100), and maximum runtime (3–60 minutes). It creates a dedicated read-only session with versioned text workloads covering explanations, specifications and scheduling analysis. It samples quota every 10 seconds while settling: at least 60 seconds for the baseline and 90 seconds after each turn, with 60 seconds of unchanged readings required. Allowance reset timestamps may vary by up to 60 seconds between reads without being treated as a new week; larger changes stop the run. Usage changes restart the stability timer; a backwards reading must recover to the highest reading seen. Sampling stops after five minutes without stability. The runtime limit includes these settling periods. The controls show elapsed time, time until the runtime limit, completed turns and sampling status; turn-limit stops are labeled partial runs. The estimator also requires stable quota readings before learning token costs. Use Models × Thinking levels to check up to six model/thinking combinations and run them sequentially. All thinking levels supported by each model are available; Low and Medium remain selected by default. Economical mode targets 2 percentage points for the first selected combination, then 1 for each remaining combination. With all six selected this is 7 points nominally. Disable economical mode for 2 points each. Turn and runtime limits apply per combination, including settling; six combinations can take up to six times the selected runtime. The controls show the order, total target, current combination and separate results with links to each benchmark session. Each handoff carries the settled allowance baseline forward; if that reading changes during the handoff, the batch stops rather than attributing the change to the next model. A partial combination, error or manual stop prevents the remaining combinations from starting. Isolated benchmark boundaries allow 1-point observations without pooling different combinations or double-counting tokens. Integer rounding uncertainty still applies; repeated sweeps may be needed for identifiable token weights and sufficient samples.

Benchmarks consume allowance only after you explicitly start them. Pause other Yacwu work first: a shared reservation permits only one benchmark across all hosts. The runner refuses to start while tasks are active and stops if other Yacwu work begins. It also stops at the observed target, turn/time limit, manual Stop, or quota reset. Targets are checked between turns, so the final turn can overshoot the requested allowance target. Closing the browser does not stop the backend runner; restarting the backend ends it and never restarts it automatically.

Quota stability is provisional, not a guarantee that accounting has finished. Pause other use of the same account outside Yacwu as well; it cannot be detected reliably. Benchmark samples and final summaries are saved with usage telemetry. These runs measure allowance use, not model answer quality, and continuing the same session includes growing context and cache reuse in the measurements.

Code maintenance

  • Shared helpers keep usage accounting, upload storage, file-change counts and relay recovery consistent; type checks reject unused locals and parameters. See the code consolidation audit for scope and remaining structural work.

License

MIT

OpenCode with Magic Context

  • OpenCode is an optional local provider with Magic Context for persistent project memory and context management, including OpenAI/Codex models authenticated through OpenCode.

Install the pinned OpenCode 2.3.0 and Magic Context 0.49.56 integration:

node scripts/install-opencode.mjs
node scripts/opencode-backend.mjs auth

The login helper uses a private server so it can coexist with an existing OpenCode managed service without competing for its port.

Choose OpenAI/Codex in OpenCode's login flow to use your supported subscription. This login is separate from Yacwu's existing Codex login. Select OpenCode in Yacwu's new-session Provider menu, then choose a model and its offered effort. Existing Codex, Claude and Copilot sessions keep their backends and histories.

Installation stays inside .workspace/opencode/, including credentials, OpenCode history, the adapter database, caches and Magic Context memory. Back up that directory if you want to preserve these sessions. The installer enables automatic discovery alongside a nonempty YACWU_BACKENDS; an explicit empty YACWU_BACKENDS= disables all optional backends, including OpenCode. Alternatively, configure opencode=node ./scripts/opencode-backend.mjs explicitly in YACWU_BACKENDS. Remove .workspace/opencode/enabled to disable automatic discovery. Installation never restarts existing backend daemons.

The managed configuration disables OpenCode's automatic compaction and pruning, pins the Magic Context plugin, disables plugin auto-updates, and turns off the periodic dreamer and embeddings. Magic Context still summarizes history and maintains project memory; its historian defaults to openai/gpt-6-luna. Set YACWU_OPENCODE_MODEL and/or YACWU_OPENCODE_HISTORIAN_MODEL in the server's environment to choose other available provider/model IDs. These settings apply when the OpenCode backend starts. /compact runs Magic Context's /ctx-wrapup, and /ctx-status shows Magic Context's own usage, compression and memory status in the thread; other /ctx-* commands can be sent directly as messages.

The historian consumes provider allowance. OpenCode's Go allowance reports rolling (5-hour) and weekly (7-day) usage through the Go gateway, authenticated with the opencode-go key OpenCode stores in its database, and Yacwu reads it into the same allowance windows as its other backends; an OpenAI/Codex login has no such allowance to report, so those windows stay hidden. Read-only access is unavailable for OpenCode in this integration. Messages sent during a running prompt are queued until that prompt finishes. Forks retain OpenCode history; model and effort choices apply on the next prompt.

Provider forks: /fork keeps the current backend and copies its native history. /fork codex, /fork claude, /fork copilot, or /fork opencode selects an enabled provider. Switching providers creates an idle session in the same local folder with the source transcript as labelled reference context and the destination's default model. It preserves file access and rejects unsupported read-only targets. Backend tool state and approvals are not migrated, and files are not copied. Small transfers (up to 512 KiB including instructions) are embedded directly. Larger transcripts are saved intact in private .workspace/fork-transcripts/ JSON files under the Yacwu installation and referenced by absolute path, so the destination can search or read relevant parts on demand. Keep those files while the fork needs its source history. Transfers over 64 MiB, more than 100 history pages, and transfers from remote machines are rejected rather than truncated.

Slash commands with finite arguments show a searchable dropdown: enabled /fork providers, /mode choices, /todo and /goal subcommands, and the session's models, reasoning efforts and profiles. Use arrows, Tab/Enter, or click to fill an option; Escape dismisses the list. Selecting a partial argument fills the draft. Enter on an already complete command submits it normally. Profile choices reuse the session's cached profile list instead of fetching on every keystroke.

About

Yet Another Codex Web UI

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages