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).
- 🖥️ 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=offturns 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=offturns 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 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.
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 |
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 -WhatIfThe 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 3001If 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.
- Gleam ≥ 1.18 with Erlang/OTP ≥ 27 (and
rebar3onPATHfor compiling one transitive Erlang dependency) —.tool-versionspins the versions for asdf users - Bun ≥ 1.3 (builds the web UI)
codexCLI onPATH, already authenticated (codex login)- Node.js ≥ 24 (portable server launcher and session relay)
- Optional Claude support: a built
claude-codexcheckout and working Claude authentication. See adapter setup.
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 -- --helpThe 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.
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.shTo 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.
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 startThe 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 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 startCopilot 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.
./scripts/build-release.sh # produces dist/yacwu-<version>.tar.gzUses 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./scripts/build-appimage.sh # produces dist/yacwu-<architecture>.AppImageRequires 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:8080The 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).
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.
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.
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,bobWhen 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.
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 runRegister 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 runWhen 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.
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.
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 singlecodex app-serverport: 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 anindex.htmlfallback.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 bythreadId.
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.
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.
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 <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.
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.
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.
- 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.
MIT
- 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 authThe 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.