octoscode-web

octoscode-web brings the interaction model of Octoscode to a browser workspace. It is intentionally separate from the general-purpose octos-web product.

Coding session (light)	Coding session (dark)

 Octoscode TUI ──┐
                 ├── Octos UI Protocol ── octos serve
octoscode-web ───┘                        agents · tools · sessions · tasks

The two clients share server-owned runtime truth. The Web app does not contain a second agent loop, plugin host, sandbox, or session store.

• Octoscode-compatible launch, prompt queue, interrupt, approval, question, command, and session behavior.
• Durable hydrate, cursor replay, deduplication, gap recovery, and reconnect. Capability-gated turn-state checks preserve uncertainty without resending.
• Saved conversation links can reopen an exact server-confirmed reference in a new browser after authentication and explicit review.
• A DSH-aligned Workspace/Session sidebar with search, New Session, Add workspace, tab-confirmed Session navigation, and Settings.
• Same-tab background continuation for server-acknowledged turns while another Session is selected or created.
• Unread tab counts and opt-in desktop notifications when hidden or background responses finish or need attention.
• Session-local Chat and Trajectory views, safe Markdown/code rendering, approvals, questions, plans, tasks, output, artifacts, and diff review.
• Server-advertised permission control and effective runtime-model status in the composer, plus capability-gated provider, model, route, credential, test, discovery, save/delete, and Profile-default management in Settings.
• Browser onboarding for an empty solo server, with transient credentials and a truthful TUI fallback on older Core versions.
• A responsive coding workspace informed by DeepSeek Harness, with its MIT attribution preserved.

See Product scope for the supported surface and deliberate non-goals.

Requires Node.js 22+ and pnpm 11.5.2.

pnpm install --frozen-lockfile
pnpm dev

Run octos serve separately, then enter its origin and optional auth token. The connection form defaults to this page's origin; Use this page restores that address after a custom server was saved. After connecting for the first time, enter a workspace path on the Octos server and select Start session. For later conversations, New Session offers recent Workspaces and Add workspace. The sidebar remembers the Sessions this tab successfully opens, so multiple conversations in the same Workspace remain distinct and can be selected again. The selected Session is restored on refresh in the same tab; only the server origin and display preferences survive after that tab closes. Unsent composer drafts survive refresh in the same tab and stay scoped to its server, sign-in and Session; they are never sent automatically after restoration. These confirmed references are navigation memory, not a complete Session catalog: Core rc.9 can misroute session/list({cwd}) for unscoped/admin connections, so the Web client cannot promise a complete or correctly grouped catalog until the server-owned SessionRef contract in octos#2146 lands. The browser cannot start or provision the Octos binary.

A turn that this tab started and Core acknowledged can keep running while you select or create another Session in the same live tab. Browser-local queued prompts still block navigation; remove unwanted entries from the queue above the composer before switching. If turn/start is awaiting acknowledgement, the Web app labels the turn Starting, remembers the latest create/switch click, and executes it exactly once after Core accepts the turn. Rejection or local cancellation drops that intent and keeps the source Session selected. Core rc.9 provides no safe post-turn release signal, so the Web app retains at most eight owner connections. Reopening one of those retained Sessions reuses its connection even at the limit; opening a ninth new target is refused until you explicitly Disconnect and reconnect. No completed owner is silently evicted. This is not detached server execution: refreshing or closing the tab, losing the network connection, or selecting Disconnect closes the owner WebSocket and Core rc.9 terminates a still-running turn. A browser leave warning helps prevent accidental refresh or close while work is active. Disconnect keeps the current tab's confirmed Session references; Forget server or changing the server identity clears them. Durable detached execution and exact stale-connection cleanup are tracked in octos#2167.

For UI work without a local Octos installation, start the deterministic AppUI fixture in another terminal:

pnpm mock:server

The getting-started guide explains both paths.

The documentation index is the complete map. Contributors should also read CONTRIBUTING.md and SECURITY.md.

apps/web          React application and feature UI
packages/client   React-free JSON-RPC/WebSocket client
e2e               Playwright product, recovery, responsive, and WCAG flows
scripts           Contract, policy, deployment, and real-Core verification
deploy            Checked same-origin nginx production reference
.github/workflows CI and immutable provenance-attested release automation
docs              product, architecture, protocol, and deployment guides
docs/adr          accepted architectural decisions

pnpm check
pnpm contract:verify
pnpm exec playwright install chromium
pnpm test:e2e

Compatibility changes should also pass the pinned real-Core integration gate; see Protocol integration.

Apache-2.0. Copied or substantially adapted third-party work is recorded in THIRD_PARTY_NOTICES.md; the generated production dependency closure is recorded in THIRD_PARTY_LICENSES.md.