MoAI Web Console
The local operations console — six areas (Overview, Factory, Specs, Monitor, Settings, Todo), live updates, read-only observation, settings editing.
MoAI Web Console is the local operations screen you open with moai web. It shows the project’s SPEC catalog, the factory lanes, sessions and goals, and verification history in one place, and lets you edit settings from the same screen. The browser connects to 127.0.0.1 only, and there is no database and no login.
InfoIn one line: the console is an operations shell that groups five observation areas and one settings area behind a left rail. The observation areas only read; the settings area uses the same validation and persistence layer as the terminal wizard.
The screen has three parts. The rail on the left stacks the six areas vertically, the appbar across the top carries the current title and status, and the rest is the body. The rail and the appbar stay in place whichever area you are in.
| Area | Route | What it does |
|---|---|---|
| Overview | / | Whole-project summary — stat tiles, in-progress SPECs, attention list, sessions |
| Factory | /factory | Factory lane list plus the four-column SPEC pipeline |
| Specs | /specs | SPEC catalog search, filters and detail, close debt and MUST-FIX drift |
| Monitor | /monitor | Sessions, goals, verification and epics in four panels |
| Settings | /settings | Profile preferences and project sections |
| Todo | /todo | The backlog queue, read-only — every card in all three states |
What sits at the right of the appbar depends on the area. The five observation areas show a live indicator; the settings area shows a save cluster (the change count and the save button). The context chips (lang · model · effort · dev) render in the settings area only — they exist so you can confirm the key values of the profile you are editing before you save.
The foot of the rail gathers the profile button, the project name, the interface-language picker and the shutdown button. Pressing the profile button opens a popover where switching, creating, renaming and deleting all happen in one place. It is the same popover from every screen, so the console has exactly one surface for handling profiles.
flowchart TD
Rail["Left rail
Overview · Factory · Specs · Monitor · Settings · Todo"]
Top["Appbar
title · live indicator / save cluster"]
Body["Body
per-area screen"]
Read["Read-only areas
Overview · Factory · Specs · Monitor · Todo"]
Write["Settings area
through the validation · persistence layer"]
Files["Project files
state and settings under .moai/"]
Rail --> Body
Top --> Body
Body --> Read
Body --> Write
Read -->|read only| Files
Write -->|save| Files
style Read fill:#E3F2FD,stroke:#1565C0
style Write fill:#FFF3E0,stroke:#E65100Overview opens with four stat tiles: SPEC (total count and how many are in progress), drift (MUST-FIX count), session (PID-confirmed count / registry count), and verify (the last verification result and the number of keys).
Below them come the in-progress SPECs list, the Needs attention panel (which collects only MUST-FIX drift, failed verification and stalled goals), and the Sessions panel on the right.
The Factory area stacks two lists of different character.
The factory lanes list gives one row per registered lane, with its session, card, SPEC and backend. The stage state is estimated from the heartbeat, so it carries an estimation mark; model, effort and context come from that session’s own telemetry record, and a cell left blank means the session has no record carrying that value yet — not filling it in is the discipline. A lane whose process id resolves to no session — or to more than one, on either registry — is marked unresolved and carries no values at all: a lookup that completes on the wrong session renders another lane’s record as if it were this one’s, which is worse than an empty row. When no lane is registered, the list says so.
The SPEC pipeline lays SPECs out in four columns by status (draft · in-progress · implemented · completed). superseded, archived and rejected never reach this list; you see them through the filter in the Specs area.
The Specs area starts with a search box and status filter chips. Two warning panels then come before the list.
- Close debt — SPECs whose implementation landed (
implemented) but whose lifecycle was never closed tocompleted. When there are many, only the most recently updated few are shown, along with the fact that the list was truncated and the total count. - MUST-FIX drift — drift that carries a remediation command. The command is copied only. The console never runs any command on the server — you copy it and run it yourself in your own terminal.
The reason both panels sit above the list is simple. When the catalog runs to hundreds of rows, anything placed below it is pushed so far down the page that it is effectively absent.
The list has columns for ID, title, status, Tier, era, updated date and drift. Selecting a row opens a detail panel on the right with the document list, the file path and the drift detail.
| Panel | What it reads |
|---|---|
| Sessions | Session id, SPEC, backend, heartbeat, working directory |
| Goals | The armed goal’s condition, turns taken, whether it has stalled, and the verdict |
| Verification | A per-key recent-history sparkline and whether it passed |
| Epics | Per-epic progress as computed by moai epic status |
The backlog queue moai todo writes gets its own address. The screen lists every card in all three states — queued, picked, dropped — with its id, text, state badge and the SPEC id it produced, if it has one. Nothing is filtered out, because the question this screen answers is “where did that card go”, and a queued-only working view cannot answer it.
It only reads. Adding, picking and dropping stay with moai todo; the console never writes to the queue and never takes its lock. Opening the page in a linked worktree shows the primary checkout’s queue, not an empty one — the queue is one channel per repository, and the header carries the directory it resolved to so you can see which file you are looking at.
A missing queue or a valid queue with no cards renders an empty-state line at HTTP 200. An unreadable queue also returns HTTP 200, but displays an unavailable notice without zero counts. Raw storage errors are not displayed.
The observation areas refresh when watched files change. The server holds an SSE stream open at GET /events, watches the project paths and resolved home directories listed below, and coalesces file events into 250-millisecond batches.
The key property is that the event carries no data. The server sends only the name of the area that changed; the browser takes that signal, re-fetches the current page and swaps the body. The truth about rendering stays in exactly one place — the server — so the screen and the files can never tell different stories.
| Event | What is watched |
|---|---|
spec | .moai/specs |
session | .moai/state |
goal | .moai/state/goal |
verify | .moai/state/verify |
factory | .moai/state/todo, the resolved home Todo directory (~/.moai/db/<project-key>/todo), and the resolved Factory directory |
config | .moai/config/sections |
Only the config event is handled differently. If the screen changed underneath you while you were editing settings, the values you were typing would disappear — so instead of refreshing, it raises a banner saying the config files changed.
Directories absent at startup are retried every second. Registering a newly created directory sends a refresh signal, including when the SSE connection is healthy. A lost connection changes the appbar indicator to disconnected; after three failed reconnection attempts, the browser falls back to polling every 30 seconds.
One discipline shows up all over the screen.
- Session liveness is raised to active only where the process was confirmed alive. A registry entry can outlive its process, so anything unconfirmed is marked stale.
- Stage state is estimated from the heartbeat, and the fact that it is an estimate is written alongside it.
- Values with no record (per-role model, effort and context usage) are left blank rather than filled in with something plausible, and a factory lane that cannot be attributed to exactly one session is marked unresolved rather than shown carrying another lane’s record.
- Empty lists are not left empty; they say so. An empty panel otherwise reads as “not read yet”.
The settings area is the only place in the console that writes files. It defines no validation rules of its own and calls the same validation and persistence layer as the terminal wizard (moai profile, moai update -c). That is why editing from either side produces the same result.
Choosing Settings in the rail unfolds the tabs below as a vertical list.
- Identity — display name and project-level identity fields
- Language — conversation, commit message, code comment and documentation language
- Claude settings — permission mode, model, effort level
- GLM Settings — per-tier GLM models, per-tier effort, GLM API key
- Codex settings — a read-only mirror gathering the scattered codex settings onto one screen: the audit backend and the codex pins, the codex opt-ins, and the detected binary. Nothing is edited here; each row links to the tab that actually owns the value
- Workflow — execution mode, default mode, agentic-loop, loop-prevention
- Git & Worktree —
git_strategy.mode, per-profilemerge_method, worktree and branch-guard toggles - Audit — the audit model and the per-backend gates
- Report — report format and output preferences
- MCP — per-tool activation toggles for
moai mcp-server. Write-capable tools carry a distinguishing mark - Cross-Session — the inbound posture for cross-session messaging: how inbound messages are handled (
accept·hold·refuse), cross-machine sending isolation, and held-dialog expiry. It editscrosssession.yaml, and the launcher injects this value into sessions from the nextmoai cc/glmrun — sessions already running keep the posture they were launched with - Feedback — the repository the feedback workflow files against, and the pre-submission confirmation toggle
- Quality Gate — whether the commit-time heavy gate runs. The runner honors this value only under
MOAI_PRECOMMIT=1
The number beside each tab is how many fields that tab renders. A tab with errors carries a warning mark instead of the number, so the list itself tells you which tab to open.
The codex settings were split between the Audit tab and the MCP tab. Answering “how does this project use codex?” meant visiting two tabs and reading values that never appeared together. The Codex settings tab puts them on one screen.
Showing without editing is a chosen trade-off, not an unfinished state. Every panel in the settings area lives inside a single <form>, and the save path reads only the first value submitted under a given name. Render the same setting as a control in two panels and the edit made in the later panel is discarded with no warning. A bool setting is worse still: its hidden companion field, standing alone, is read as an explicit false, so merely opening this page and saving would switch six MCP tool toggles off.
So the Codex settings tab renders values and links, and creates no input element carrying a name. Every setting stays declared, rendered and editable on its owning tab. “Fixing” this page into editable inputs later would reintroduce exactly that loss.
Nothing new was configured. No new configuration key, no new persistence route, no new file under .moai/config. The settings already existed; only the place to see them together is new.
The MCP tool toggles are often empty on disk, and the console reads an empty value as on. Rather than interpreting that emptiness itself — which would make this page a second classifier — the tab prints (unset) and states the fact in the group heading: an unset value reads as enabled, and only an explicit false turns a tool off.
Fields render with the widget that matches the value’s real domain. A bool field is drawn as a two-option radio group rather than a checkbox — a checkbox hides the current choice, a radio pair reveals it. Closed sets such as execution_mode or audit.model are select boxes or radio groups, and values outside the set are rejected on save. Only genuinely open domains, such as repository paths or API keys, stay free text.
The only runtime delivery channel for effort is a single session-level environment variable, so per-tier effort values are stored only. They persist in the config, but the runtime reads only the session-level value. The GLM Settings tab carries a badge naming the source that actually applies, so this is stated rather than implied.
What can be edited is fixed by a single source of truth, and the console writes only inside it. user, language, quality, git-convention, git-strategy and llm save through the typed validation path; workflow and report save through a seam that preserves the comments and line order inside the file. Machine and state sections and the large policy files are excluded, and a new section is refused by default until it is explicitly listed. The keys in each section are covered in the configuration sections reference.
Loopback only. The console binds to 127.0.0.1 alone, so a remote host cannot reach it. Loopback is not divided by account, though: another account logged in to the same machine can connect to the port.
No database. Nothing extra is started. Everything it reads and writes lives in files under the current project’s .moai/.
No authentication. There is no login or token layer. Binding to loopback keeps remote hosts out, but not other accounts on the same machine. On a shared machine, those accounts can reach the console while it is running.
No command execution. The observation areas refuse any method other than GET, and no screen runs a command on the server. The console does not perform SPEC status transitions either — those belong to each phase’s manager agent.
Host check on every request. Every route, static files included, refuses any request — regardless of method — whose Host header is not a loopback name (localhost, 127.0.0.1, [::1], with or without a port) or has no Host header at all; the response is 403. Loopback binding alone does not stop DNS rebinding — a page on another site can make the browser connect to 127.0.0.1 while carrying the attacker’s domain as Host, and the browser then lets that page read the response. The same-origin (Sec-Fetch-Site) check still applies only to state-changing requests.
InfoLoopback-only is what makes no-authentication acceptable. Exposing the console externally through a reverse proxy or a0.0.0.0bind is not supported. If you need to view it remotely, forward the local port over an SSH tunnel. An SSH tunnel still works with this check, since the browser still opens the console at alocalhostaddress. That said, this was confirmed in a test setup that simulates port forwarding rather than a real SSH server, so treat it as expected behavior rather than a verified guarantee.
The interface language is chosen from the picker at the foot of the rail: English · 한국어 · 日本語 · 中文. The choice persists in the browser and applies from the first paint the next time you open it. It is the same language set as the docs-site four-locale documentation, so you can read the screen and the docs in the same language.
Running moai web in a project directory binds 127.0.0.1:3041 and opens a browser automatically.
| Flag | Default | Behavior |
|---|---|---|
--port <int> | 3041 | The loopback port to bind |
--no-open | false | Do not open the browser automatically |
--no-reuse | false | Do not reclaim the port from a stale moai instance; fail on a conflict instead |
To stop it, press Ctrl+C in the terminal or use the shutdown button at the foot of the rail. For the details see the CLI reference — moai web.
- CLI reference — moai web — flags and route detail
- Factory Mode — the source contract for the chain the console draws
- Configuration sections reference — the keys the settings area handles
- moai epic status — the producer behind Monitor’s epic panel