# OSCODE Web CLI · 0.24.0

Run in your project with Node.js 22 or later:

```sh
npx @choijinwon/oscode@latest --web
# Optional no-key demo that reads the real project file list
npx @choijinwon/oscode@latest --web --demo
```

Add `--cwd /path/to/project` to choose a project. Keep the terminal running and open its local URL. Existing CLI model settings, environment variables and saved credentials are reused. API keys are not sent to the browser. The demo is not a coding model.

## Interface language

Choose **한국어 / English / 日本語** in the language selector at the bottom of the sidebar. Menus, settings and primary controls update without reloading, and your choice is remembered in the same browser. Drafts, model IDs, file paths and conversation content stay unchanged. This controls the interface language; request your preferred response language in the conversation.


## Chat and tasks

Enter sends a request; Shift+Enter inserts a newline. Up to eight conversations can be created. Submit additional requests while work runs to queue them. Each request receives an `OSC-…` ID, with copy and navigation to the associated conversation. Filter all tasks, approvals, upcoming work or finished tasks.

File changes and commands require per-action approval; existing deny permissions remain effective. Shell commands can affect files outside the project: this is not an operating-system sandbox. Approved, rejected and expired requests are recorded against the task.

Use the time selector above the composer to schedule a task in your local timezone. This is the earliest possible start, not a guaranteed deadline. One project task runs at a time. Pending tasks can be cancelled; active tasks can be stopped. A completed response means the agent turn ended, not that the business outcome or artifact quality was verified.

Open task details for a two-column timeline: tool steps on the left, actual inputs, change previews, outputs and duration on the right. Duration includes approval waits. At most the latest 100 tool records per conversation are retained. Long output can be truncated by existing tool limits.

## Live browser

Open the live browser using the left rail and enter your development URL. An isolated Chromium window is captured roughly once per second. Manual control supports clicking, wheel scrolling, text input through the bottom field, supported keys, back and reload.

Hand control to the agent before asking it to use `browser_live`. Every agent browser action uses the existing approval flow. Return to chat to approve it. Taking control back requests cancellation of a linked task; an already started action may finish. Stop closes the browser; closing its panel only hides the view.

If Chromium cannot start:

```sh
npx playwright install chromium
```

Personal cookies and logins are not shared. A single 1280×800 tab is supported. Popups, downloads, uploads, native browser dialogs and full desktop control are not included. The model receives bounded page text and controls, not the screenshot stream. Opening a page makes network requests to the target site. Browser state is discarded when closed.

## Persistence and limits

This server is local only. Do not share its capability URL or expose it with a public proxy. Up to 100 tasks per server. Task lists, schedules and approval records live in memory and are not restored after restart. Conversations and tool execution records are saved in `.oscode`; past-session selection after restart is not available in this UI yet.

A connected browser is required for the queue to run. After 30 seconds without one, active work receives a cancellation request. Pending tasks resume when the browser reconnects. Browser timer throttling may cause cancellation in long-hidden tabs. Server shutdown cancels pending reservations. Recurring schedules, calendars and external event triggers are not supported.

Full CLI slash-command parity, MCP configuration, attachments and changing models through the web interface are not yet available. Configure the model through the existing CLI and restart the server. Some interface labels remain Korean.


## Repository development version

These additions are not included in the already published npm 0.19.0 package:

- Model settings and an explicit, potentially billable connection test. Provider/model/endpoint/budget are saved in oscode.json; a newly entered API key stays in server memory only. Configure while the queue is empty and all work is idle.
- Search and select up to eight project text files, 24KB each and 48KB combined. Preview attachment token estimates. Secret paths and paths outside the project are excluded.
- Safe headings, lists, bold text, code blocks with separate copy buttons, and simple tables. HTML is treated as text; syntax-specific highlighting is not included.
- Compare checkpoint content with the current file and restore only when no later edit conflicts. Shell side effects are not covered.
- Restore saved conversations and task records. Incomplete tasks are cancelled on recovery and never replayed automatically.
- Display usage/budget and draft estimates. Estimates are heuristic and attachments are counted separately.
- Prepare an actual ui_check request with URL and optional scenario. Show actual output and captured images. No scenario means button behavior remains unverified.
- Dock the live browser beside the conversation on desktop with the split-view button.
- New task result cards show per-task input/output tokens, model requests, failed tools and checkpoint file changes. Verification execution is distinguished from a passing result.
- Failure-specific guidance covers output limits, budgets, authentication and network errors. Resume prepares a draft asking the agent to inspect current state first; it does not replay commands or submit automatically.
- Cumulative usage is displayed separately from the per-task budget. Cumulative usage alone does not block the next request. Settings include a maximum output token limit, subject to provider/model restrictions.
- Task templates prepare screen implementation, bug fixing, component reuse and accessibility/responsive review drafts. Existing text is preserved; replace placeholders and submit manually.
- Search task titles, requests and IDs together with the status filter. All space-separated search words must match.
- Download a local Markdown task report with recorded status, usage, checkpoint changes, verification execution and approval descriptions. Missing historical summaries are explicitly marked. Raw conversations and tool payloads are excluded; review titles, paths and approval descriptions before sharing.

## Development version: personal assistant profile

Use **비서 프로필** above the composer to set a 1–24 character name, a PNG/JPEG/WebP image up to 768KB and developer/personal-assistant mode. Save to update the navigation icon, profile, favicon and running-task image. The default cat image can be restored.

Personal-assistant mode offers daily priorities, meeting notes, document drafting and handover templates. Templates only prepare a draft; submit manually. This mode changes UI templates, not model permissions. Preferences persist per project in `.oscode/web-profile.json`; images are not uploaded externally or sent to the model. Email/calendar integration and an always-on background assistant are not included. These changes are available in the repository development version; npm/public release is separate.

### Today's work

The **오늘의 업무** sidebar button opens a live overview of tasks in all currently loaded conversations for this project. Personal-assistant mode opens it on startup. It includes pending approvals and running work from earlier dates, today's queued/scheduled work (including earlier unstarted reservations), responses finished today, and today's failed/stopped tasks. Calendar boundaries use browser-local time.

Approval review navigates to the real approval card without approving automatically. Task/detail buttons open actual records. Completed responses are not proof of successful work or passing verification. Future reservations, cancellations and unloaded historical sessions are excluded. This overview does not sync an external calendar or a separate manual to-do list.

### Notifications, result shelf and personal templates

The notification center keeps up to 50 new terminal-task/approval events observed by this tab, without duplicate polling notifications. Reloading clears its history. Enable browser notifications explicitly; they show status/task ID rather than request text, require permission and an active server/tab connection, and may be unavailable in some browsers.

The result shelf shows the current conversation's task reports, current file contents from the latest 30 file-tool checkpoints (deduplicated by path), and registered ui_check screenshots. Preview/download text reports and changed files. Unreadable files are excluded from downloads; shell-created files are not collected automatically. Review content before sharing.

Save and edit up to 20 project-specific personal templates (60-character name, 8,000-character request) in `.oscode/web-templates.json`. Selection appends a draft without sending it. Attachments are not saved. Do not store credentials in templates.

### HTML previews from chat

Click **HTML 미리보기** on a completed HTML code block to render it without saving files. The composer toolbar also opens an HTML editor with manual run and download buttons. Scripts are disabled by default; explicitly enable inline JavaScript and rerun to test button interactions. The sandbox blocks form submission, popups, external resources/API calls and access to OSCODE's document/files. JSX, Vue SFCs and package-dependent sources need built HTML or the existing live-browser workflow.

0.24.0 keeps a newly opened preview when an older preview response arrives late. Late responses from previous settings, file and other views also preserve the inputs and controls in the current view.

Switch desktop/390px mobile views. Previews live only in local-server memory (up to 20, 96KB each, 15-minute expiry) and the current preview is removed on close. No model request or project write is required. Rendering, optional scripts, isolation and mobile sizing were tested in Chromium, Firefox and WebKit. This is engine coverage, not a guarantee for every browser version/device; notification support remains browser-specific.

## Connect plugins

Use **플러그인 연결 (Connect plugins)** in the composer toolbar to register MCP-compatible servers. Local stdio accepts an executable, a JSON argument array, and environment variable names. Remote HTTP supports no authentication, an environment token, or browser OAuth. Never enter secret values into the registration fields.

Registration saves `.oscode/mcp.json` without starting the server. Explicitly approve the connection, then select the tools to expose to the agent. Actual tool execution follows existing approvals and permissions. Up to 10 servers can be registered, with 3 concurrent connections and 8 selected tools per conversation. Connections and selections are not restored after restart. Finish or cancel active and queued tasks before changing plugins. Browser extensions and arbitrary npm packages require an MCP server adapter.

## Framework preview

**프레임워크 미리보기 (Framework preview)** uses the actual project development server, separately from static HTML preview. Inspect a project folder to detect React, Vue, Angular, Svelte, Next.js or Nuxt and select a declared dev/start/serve/preview script. Review its command before approving `npm run SCRIPT`; npm lifecycle scripts can also execute. Dependencies are not installed automatically.

Set the actual localhost URL shown by the development server, then open the working browser to click, type and scroll. An already-running server can be opened without starting another process. Source updates follow the framework's HMR configuration. Stop only servers started by OSCODE; these are also cleaned up on OSCODE shutdown. Suggested ports do not override scripts. Embedded browsing requires Playwright Chromium. Standalone JSX/SFC snippets need a configured project, and dependency detection does not certify compilation. Logs remain in memory, limited to the last 16,000 characters.

## Select elements and review screen changes

Open the work browser, take manual control, and choose **화면 요소 선택** (Select element). Clicking the captured screen identifies a DOM element without activating it. Enter your change and choose **수정 요청 초안 작성** to prepare a chat draft; sending remains a separate action. Runtime selectors and styles are clues, not verified source locations.

Save a baseline with **수정 전 화면 저장**, then compare the same URL with **수정 전후 비교**. The 1280×800 before/current/diff images show pixel changes, including dynamic content. They do not prove functional correctness. Accepting updates only the baseline; requesting rework prepares a draft, without sending it or committing code.

**브라우저 작업 기록** displays up to 20 post-action snapshots without replaying actions. Direct keyboard text insertion is not listed. History is cleared when the browser stops or the server exits. Start detailed tracing only after consent, then stop and download a real Playwright Trace ZIP (maximum 16 MiB). Traces may contain sensitive DOM, screen and network data. Open them manually in Playwright Trace Viewer; OSCODE does not automatically upload traces to an external viewer.

## Framework connection helper

**프론트 앱 폴더 자동 찾기** discovers frontend apps within up to 3,000 files and 40 package manifests. It suggests declared or default ports and reports a local `node_modules` directory; monorepos may use a parent directory. Explicitly apply a localhost URL detected in logs using **로그에서 발견한 주소 적용**. Diagnostics distinguish missing servers, stopped scripts and HTTP errors. OSCODE's own CLI script is rejected as a frontend preview target.

## Work recipes and model costs

**업무 레시피** connects AI tasks and human review steps. Save up to 10 recipes with 1–8 steps each in `.oscode/web-recipes.json`. Replace placeholders in the screen-improvement or briefing examples. Starting and advancing each step require explicit approval; preceding tasks must finish. Task completion means a response finished, so review the actual result yourself. Failed or stopped tasks do not advance automatically. Up to 20 execution records are kept in memory, without restart recovery or recurring scheduling.

**모델 비용 단가** sets exact-model API prices in USD per million tokens for Anthropic or compatible APIs, with optional cache read/write rates. Future requests retain their rate snapshot. Task cards show the model, actual MCP tool-call count, and estimated cost; missing rates remain unknown, separate from any partial subtotal. ChatGPT subscription charges and MCP service fees are excluded. Estimates are not invoices.

## Workspace extensions

See the [Workspace guide](./work-studio.en.md) for recorded test drafts, completion checks, the module canvas, impact analysis, implementation comparison, failure grouping, evidence export, task reuse, event proposals and semiconductor model evaluation.

## Model connections

See [model connection guide](model-connections.en.md) for presets, discovery, tool probes and compatibility options.

See [reliable work and preview](reliable-workflows.en.md) for recovery, reuse, model policies, regression gates, verified file promotion and responsive/offline preview.

## Storage warnings and shutdown

The named sidebar contains Today, Chat, Tasks, Outputs, Workspace and Connections (currently Korean labels). Badges show pending approvals, running/queued tasks and connection-check or web transport errors observed in this tab. They are live indicators, not a persistent error history. Opening Connections does not start model requests or MCP connections; model configuration is distinct from a successful connection check.

Preview is available in the chat header. Settings, Profile and the conversation list toggle sit at the bottom of the sidebar. On mobile, Chat closes the activity panel and focuses the composer.

Failed task journal writes display a storage warning. Check disk space, project write permissions and the `.oscode` files. A successful write of the latest snapshot clears the warning. Recovery after a restart cannot be assured while it remains visible.

`Ctrl+C` waits for cancellation, development server/browser/MCP cleanup and the final task journal write. Force-killing the process may interrupt this sequence. A result collection error appears separately from execution status and does not replace the original execution error.

## Agent assignments

Open **Agent assignments** above the composer, enter your request and approve the AI delegation proposal. The lead agent analyzes the project with read-only tools and proposes up to three roles. Reopen the menu when it finishes, review or edit each `name`, `prompt` and `readOnly` field, then approve child agents.

Each child runs in a separate conversation with the current model settings. Execution is sequential in the same project, with up to 8,000 characters of the preceding agent's actual response passed as reference data. Read-only roles cannot edit files or run shell tools. Implementation roles retain existing tool approval rules. These are shared-project sessions, not isolated file copies or automatic merge branches.

Task details group actual tool records, status, token usage and responses by agent. Stop individual agents or the entire group. Failed or interrupted predecessors block downstream model calls. Explicit retry runs only the selected agent as a new task; earlier file changes are not rolled back. Recover the predecessor before retrying downstream agents. After server restart, restore the related conversations to see the complete timeline.

Each role incurs separate model costs. Prefer a single agent for small tasks, and bound delegated work with concrete acceptance criteria. A completed response does not mean verification passed.

## Fill web forms from file data

Open **Data entry** in the live browser. Import UTF-8 CSV/TSV (up to 1 MB) or XLSX (up to 2 MB, Python 3 required). The first row must contain unique column names; limits are 300 data rows and 40 columns. XLSX uses raw stored values from the first visible sheet, without date/currency formatting. Formula/error cells and merged cells are rejected. Convert legacy XLS to CSV/XLSX first.

Find page fields, map columns, select a row, and review the destination URL and values. Matching names suggest mappings that you can edit. Text inputs, textareas, native select options (actual option values), and checkboxes (true/false, 1/0, yes/no) are supported. Password, hidden, file, radio, iframe and custom widget fields are excluded.

Approve filling one row. OSCODE reads values back to verify them; this does not establish server-side persistence. Websites that autosave on input may change data during filling. To submit, select a button and a unique success CSS selector that is not visible before submission. A separate approval submits this exact row once. A newly visible success element counts as a page-level confirmation, not an independent database/API check.

Proceed row by row. Failed input can be reviewed and retried. Uncertain submissions cannot be resent automatically. Confirmed duplicate values for the same destination and submit button are blocked within the current run; deduplication does not extend across separate runs or restarts. Export row-status records without source values, or delete the imported data. Data and progress remain in local server memory and disappear on shutdown. Browser stop/takeover interrupts work but cannot undo already sent requests. No unattended bulk submission or cloud remote desktop is included.

### Pick completion indicators, save mappings, and validate data

Use **Pick success indicator on screen** after a manual save. Selecting an element extracts its selector without clicking the actual website. Return to a fresh form before reviewing the next input. Esc cancels selection. The unique success element must be absent/hidden before submission and appear afterward; this still does not independently verify server persistence.

Configure required values, unique values, valid ISO calendar dates (YYYY-MM-DD), or decimal amounts with up to two fractional digits and no currency symbols/group separators. Optional full-row duplicate checks mark both duplicate rows. Errors identify rows/columns and block preview of the affected row. Edit the selected row and check again. No automatic conversion occurs. Rules apply to connected columns; submitted or uncertain rows cannot be edited.

Save a named site entry rule containing column names, field labels/types, submit button, completion selector and validation configuration. Source values and filenames are not stored. Up to 50 rules persist in a private project journal across restarts; uploaded data and run progress still remain in memory. Application requires the same origin/path and unique matching field labels/types and column names. Field IDs can be rebound; completion selectors must be rechecked after page changes. Applying a rule does not fill or submit automatically and preserves preview/approval requirements.

## Assistant workspaces

Choose **Personal assistant**, **Development assistant**, or **Specialist assistant** in the left rail. Each provides a distinct welcome screen, request shortcuts and accent color. Shortcuts fill a draft; they do not send a model request. Switching keeps per-conversation drafts. Start a new chat when the selected assistant has no open conversation.

The conversation list defaults to the selected assistant. **All conversations** searches and selects every assistant's open conversations. The existing eight-session limit is shared across assistants. Load archived conversations using **Previous conversations**. Selecting a conversation switches to its assigned assistant.

**Profile** saves the current assistant's name and image separately in the private project file `.oscode/web-assistants.json`. Legacy profiles remain available; conversations without an assigned assistant follow the legacy personal/development mode.

**Change assigned assistant** requires explicit confirmation that history and attachments stay with the same conversation. Model settings and existing records stay unchanged; no tool or task is rerun. Conversations with running, approval-pending, queued or scheduled work cannot be reassigned. Ownership is saved with the conversation and survives restoration.

These are workflow views, not file-access or permission isolation boundaries. Project files and model settings remain shared under the existing approval rules. The tasks and approval views still show work across assistants. Semiconductor/ERP shortcuts are review drafts; configure actual inspection endpoints in the existing workspace.

### Create a custom assistant

Use **Assistant → ＋ Add assistant** to set its name, responsibilities, default guidance, accent color, model ID, project skill and quick request draft. Confirm that guidance and the selected skill may be sent to the model, then create it. Change its image later in **Profile**. A project can contain up to 12 assistants, including the three built-in views; the eight-open-conversation limit remains shared.

Creation does not call a model or start work. The assistant has its own welcome view and filtered conversation list. Start a new chat; quick requests only fill the input draft.

A blank model ID uses the existing connection. A specified ID applies to new/restored conversations using that connection's provider and credentials. The provider controls compatibility and pricing. Reassigning an existing conversation does not change its current model. Choose a local `.oscode/skills` entry; the file is reread for each request. A missing skill stops the request instead of silently ignoring it.

Guidance and skills do not grant additional tool permissions or file access. Definitions and profiles persist in private project storage, with legacy profile records supported. User-authored names and responsibilities remain unchanged when switching interface language.


### Draft recovery and request history

Draft text is saved in this tab's `sessionStorage`, scoped to the Web CLI address. Reloading the same address restores drafts per conversation. Successfully queued requests clear their draft. Recovery retains the latest 32 drafts, up to 16,384 characters each. Longer drafts remain editable but are not persisted. Closing the tab, changing the address, or disabling browser storage prevents recovery. Attachments are not restored. Draft text is not sent to the server or other tabs; clear the input on shared devices.

Use **Request history** to search user requests loaded in the current conversation (up to 100 matching entries). **Add to draft** appends the selected text to the composer without executing or resending it. Review attachments and scheduling before sending.


### Completion criteria and verification reports

Use **Completion criteria** above the composer to enter up to 12 criteria, one per line, up to 500 characters each. Criteria apply to the next submitted task in this conversation and are included in the model request. Unsubmitted criteria are memory-only and disappear on reload. Submitted criteria and review records persist in the existing task journal and recovery flow.

Execution ending does not automatically pass criteria. After execution, select **Review completion criteria**, choose pending/passed/failed for each item, and record evidence. Passed and failed assessments require evidence. **User review passed** requires completed execution and all criteria passed. It represents human-entered evidence, not automated test success or deployment approval.

**Download verification report** exports execution, criteria, human review, existing tool checks, file changes, estimated costs and approval history as `oscode-task-report/1` JSON. Older tasks without criteria also support export. Review requests, paths and evidence before sharing reports.

## Workflow extensions (source preview)

See the [workflow guide](web-workflows.md) for the work inbox, editable approvals, background schedules, selected-element source candidates, evidence cards and semiconductor comparisons. These changes are not yet included in npm 0.24.0.