@scene-glass/devtools

Review the page you're building, straight from the browser, with a loopback-only MCP bridge your coding agent can read.

This package installs into a Vue 3 or React project that already runs Vite. It adds a dev-only Vite plugin, a foreground MCP service on 127.0.0.1:4175, and a browser panel that stores annotations inside your project. Nothing it does reaches the network beyond loopback.

Install it from the public npm registry. Exact upstream OMO, Claude Code and Codex packages arrive through the release's dependencies. Scene Glass publishes devtools and one metadata-only OMO carrier, not vendor runtime payloads; setup verifies the installed sources and never downloads.

Requirements

| Requirement | Supported | | ----------- | ---------------------------------------------------------------------------------- | | Platform | darwin-arm64, darwin-x64, linux-x64-gnu (glibc >= 2.33) | | Node.js | >=24 <25 | | Vite | >=7.3.6 <8 | | Host | Vue 3 + Vite SPA (@vitejs/plugin-vue), React + Vite SPA (@vitejs/plugin-react) |

Windows isn't supported. Neither are SSR hosts, service worker / PWA hosts, static HTML sites, or Next.js: setup inspects the project and exits before touching anything when the shape isn't one of the two supported ones.

Platform errors

SCG_NATIVE_TUPLE_UNSUPPORTED from setup or start means the operating system, CPU architecture, or libc does not meet the Requirements above. On Linux, Scene Glass requires x86_64 GNU/Linux with glibc 2.33 or newer; musl is unsupported. Check ldd --version. If glibc is older, upgrade your Linux distribution to one providing glibc >= 2.33, then retry the command, or use a supported macOS tuple. Scene Glass does not compile a replacement addon on unsupported hosts.

Install

Run this in your project root:

npm install --save-dev --save-exact --ignore-scripts @scene-glass/devtools

The version is pinned exactly and no install scripts run. The package ships prebuilt binaries for the platforms listed above; it never compiles on your machine.

Set up

npx scene-glass setup

Setup takes no parameters except --runtimes-only (below). It inspects the current project, shows a secret-redacted preview with an approval digest, and waits for you to approve. Decline and nothing is written. After approval it:

• adds one sceneGlass() plugin entry and its import to vite.config.ts;
• writes a gitignored .env.development.local credential;
• writes lifecycle state under <project-root>/.scg/;
• runs a live MCP and browser diagnostic;
• verifies the OMO, Claude Code and Codex runtime packages this release pins and reports each one, then exits.

Your index.html, package.json, lockfile, and node_modules are left alone.

Runtime sources are exact registry dependencies: the metadata-only @scene-glass/runtime-omo-darwin-arm64 carrier, official @anthropic-ai/claude-agent-sdk-darwin-arm64, and the @openai/codex-darwin-arm64 acquisition alias for OpenAI's native package. Scene Glass verifies complete vendor-owned packages in project node_modules against dist/runtime-authorities.json, whose digest is embedded in the bundle. Setup only checks these sources offline; it never downloads or writes a HOME runtime store. Production catalogue entries remain TODO-RELEASE until qualification.

Installed size is not yet measured for this acquisition graph. OMO and Claude share the SDK sidecar source; package version and executed Claude Code product version are separately pinned. OMO runs on the server's bound Node 24 and qualified ABI. All execution uses independently copied, frozen temporary snapshots. OMO preparation uses a pinned byte recipe and complete output verification. Codex's voice host remains verified on disk but is excluded from the execution snapshot; code mode stays.

If your install skipped optional packages (for example with --omit=optional or an omit setting in .npmrc), the runtimes are missing and setup says so. Bring them back with:

npm install --include=optional

Every launch still checks the complete inventory and runs from a sealed temporary copy, so a changed or partial runtime fails closed even if setup was skipped.

To check only the runtimes, without touching the project:

npx scene-glass setup --runtimes-only

It ends with SCG_RUNTIMES_READY, or exits non-zero with SCG_RUNTIMES_INCOMPLETE.

Run it: two processes, both in the foreground

Scene Glass never starts itself and never runs as a daemon. You run two processes, in two terminals, from your project root.

Terminal one, the Scene Glass MCP service on 127.0.0.1:4175:

npx scene-glass start

Terminal two, your own dev server, unchanged:

npm run dev

Start Scene Glass first. The plugin checks for the runtime while Vite boots, so a Vite server started first logs [scene-glass] runtime unavailable; development injection disabled. and stays inert until it's restarted.

start takes no parameters either. One process serves every project registered in the same configuration home, so don't start a second one: it'll fail its preflight because 4175 is already bound. Stop it with Ctrl+C; your Vite dev servers keep running.

Open the exact http://127.0.0.1:<port> URL that start prints, and hard-refresh once on first load. The plugin serves the loader only for that host, so the localhost spelling of the same port returns 404. When your dev server doesn't listen on 127.0.0.1 already, set server.host: '127.0.0.1' in vite.config.ts.

If the page loads without the panel, that's the intended fail-open behavior: your app stays usable when Scene Glass isn't reachable.

Settings and measurement

Open 설정 beside the minimize button to choose the work provider, model, reasoning effort, and panel side. Model and effort choices come from the installed provider's supported capabilities. An unavailable catalog is shown as unavailable, never replaced with a guessed list. Inherited settings leave provider/session defaults in control. Changing a model clears the explicit effort; changing provider clears both overrides. Provider settings are saved for the project and cannot change during active work.

Left/right panel placement is stored locally per project. If browser storage is unavailable, the chosen side lasts for the current page and the panel reports that it could not persist it. Work request controls remain on the main panel when settings is closed.

Clicking a changed memo or its numbered badge confirms that exact item. Once every applicable member of the pending request has been confirmed, Scene Glass acknowledges the request review; the review button disappears after the server confirms it. Partial or stale confirmation never completes review. The single 검토 완료 button remains the explicit path when individual confirmation is incomplete or unavailable; the separate 수정 체크 완료 control is removed.

현재 페이지 복사 uses the work-request eligible memo set and order, excluding already-consumed exact versions and unresolved/lost entries. Editing a memo makes its new version eligible under the same work rules. Empty eligibility never falls back to copying the entire page. Explicit single-memo and project-wide exports retain their separate scope.

Each project keeps one private conversation per provider, and consecutive requests on the same provider and model continue it, including after a restart. Each OMO request runs in its own OMO process that Scene Glass starts and stops, never in the shared OMO daemon, with a private copy of your OMO settings and credentials that is removed when the request ends (or, after a crash, when the next start recovers it). Processes the request started, such as a dev server the agent launched, are stopped when it ends; processes you started are never touched. A background process that lost both its hidden per-request tag and its parent before any check (for example a detached Apple system program such as sleep), or work handed to an outside service, is not tracked.

새 세션 시작 makes the selected provider's next request start a new conversation without contacting any model; the old conversation stays on disk. Changing the model starts a new conversation for every provider; changing only the effort keeps it. If Scene Glass cannot confirm that a previous request fully stopped, the next request starts in a new conversation and a warning names the earlier request; nothing is blocked. Scene Glass does not patch OMO, Senpi, Codex, or Claude.

The 0.1.20 upgrade did not migrate conversations from 0.1.19: every provider started a new conversation, the old conversation files stayed unchanged, and a request that may still have been running at upgrade was named in a warning and never resumed or re-sent.

Distance and size measurement are included; no coupon or coupon service is required. Starting a measurement loads the packaged, integrity-bound ESM/CSS pair through the authenticated dev-only Vite routes. Stylesheet readiness, artifact hashes, ABI, Origin, project, session, and filesystem checks remain enforced. Navigation, disconnect, and teardown dispose the measurement lease. Legacy coupon query parameters and attributes are stripped without validation or forwarding. Existing coupon infrastructure is retained but unused by this activation path.

Signing in to Claude Code and Codex

Scene Glass does not sign you in and stores no provider credentials. Its pinned runtimes use the sign-in the official CLI saved in your home directory (for Claude Code also the macOS keychain), or ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN for Claude Code and OPENAI_API_KEY for Codex. Install the official Claude Code or Codex CLI and sign in once before you select that provider; its own version doesn't matter. Without a sign-in only that provider shows 제공자 로그인이 필요합니다. Signing out or switching accounts in the official CLI applies to Scene Glass too.

The OMO runtime

OMO Native runs only the exact OMO runtime this release approves for your platform, together with the owned RPC protocol it checks before any prompt. A matching version string isn't enough. Scene Glass never uses an omo or node from your PATH, and never changes your global OMO installation or settings. The runtime comes from @scene-glass/runtime-omo-darwin-arm64 in your project's node_modules and runs on the same Node 24 interpreter as Scene Glass; Claude Code bytes come from @anthropic-ai/claude-agent-sdk-darwin-arm64. Both are checked against the embedded pin before every launch. dist/omo-runtime-artifacts.json is a readable copy of that pin.

If OMO can't launch, only OMO becomes unavailable, and settings and the failed request show why:

• SCG_OMO_RUNTIME_MISSING: the runtime package isn't in node_modules. Run npm install --include=optional, then submit a new request.
• SCG_OMO_RUNTIME_INTEGRITY: the installed runtime package was altered, or the Node running Scene Glass isn't the Node 24 ABI the release qualified. Reinstall the exact devtools version (rm -rf node_modules then npm install), or switch to Node 24.
• SCG_OMO_RUNTIME_UNSUPPORTED: the OMO work provider is claimed on darwin-arm64 only. New upstream x64 PTY prebuilds now load and run a child in exploratory Rosetta/Docker probes, but claim expansion still needs all three companions and full qualification. Scene Glass setup/start and its x64 secure-read prebuilds are separate; reinstalling OMO cannot expand the work-provider claim.
• SCG_OMO_RUNTIME_AUTHORITY_ABSENT: this build carries no approved runtime; use a release build.

Refused requests were never sent and are never replayed. A conversation the approved runtime can't reopen fails with SCG_OMO_CONVERSATION_INCOMPATIBLE, keeps its bytes, and continues only after 새 세션 시작. Recovery from a bad runtime is always a newer forward release, never a package downgrade. Qualification uses a loopback model and doesn't certify live subscriptions. The repository's docs/operations/omo-runtime.md covers repair, maintainer qualification and adoption, and the runtime license inventory.

Upgrade and recovery

0.1.32로 업그레이드한 뒤 0.1.31의 Claude/Codex 대화는 새 세션 시작으로 이어가며 기존 대화는 보존되고, OMO 대화는 이전처럼 계속됩니다.

Upgrades are one exact-version install followed by one setup, which re-verifies the installed artifacts against the release manifest, migrates lifecycle state from the prior release, and verifies the new release's runtime packages, which arrive in the same install. Skipped releases back to 0.1.19 upgrade in the same single setup; an unknown older release is rejected:

npm install --save-dev --save-exact --ignore-scripts @scene-glass/[email protected]

npx scene-glass setup

If an upgrade stops with a recovery-required receipt, don't hand-edit .scg/. Rerun setup to finish the crash-safe migration, or reverse the integration:

npx scene-glass uninstall

Uninstall is provenance-first. It validates every owned target before changing anything, removes only what setup still owns (the plugin entry, the credential file it created, its own lifecycle state), and never touches your annotations under <project-root>/.scg/annotations.

What this protects, and what it doesn't

Be clear-eyed about the boundary:

• The npm tarball contains the premium measurement ESM and CSS as plain, minified bytes. Anyone who installs the package can extract them and import them directly. There's no obfuscation strong enough to stop that, and no attempt to pretend otherwise.
• Authenticated local routes and integrity checks protect the supported measurement activation path.
• There's no DRM, no license enforcement in the runtime, no delivery control over which bytes reach a machine, and no way to unload code a browser has already loaded.
• The package ships without sourcemaps or TypeScript source, and its artifacts are hash-pinned in release-manifest.json. That raises the cost of analysis. It doesn't make extraction impossible.

The measurement module sits behind a fixed provider ABI (abiVersion: 1, module id scene-glass-premium-measurement-v1). That seam exists so a future release can migrate to a different delivery model without breaking hosts. No remote provider ships in this release, and none is implied by the seam.

Where things live

| Path | Contents | | --------------------------------------- | -------------------------------------------------------------- | | ~/.scg/config.json | Schema-v1 project configuration and environment variable names | | ~/.scg/credential-authorities.v1.json | Secretless credential path and device/inode authority | | node_modules/@scene-glass/runtime-* | Pinned provider runtimes, installed and removed by npm | | <project-root>/.scg/annotations | Your annotations; never rewritten or removed by uninstall | | <project-root>/.scg/onboarding | Lifecycle manifest, WAL, and receipts | | <project-root>/.scg/runtime | Setup-owned host descriptor | | <project-root>/.env.development.local | Gitignored host credential, deleted only if setup created it |