Skopeo

Visual UI context for AI coding workflows, captured from your real local browser preview.

Skopeo lets you point at the exact interface you want changed, attach a note or visual specification, inspect the source that owns it, and hand structured context to the coding agent you already use.

Quick start

1. Open your web project in VS Code or a compatible VS Code-based IDE.
2. Start your local development server.
3. Open the Skopeo Activity Bar view.
4. Enter a local HTTP URL such as http://localhost:3000 or http://localhost:5173.
5. Open the preview through Skopeo.
6. Turn on Annotate.
7. Click the exact UI element you want to change.
8. Write the requested change, optionally use Draw, inspect Source, then use Send to hand the context to your coding workflow.

Main preview controls

The top toolbar stays intentionally small:

Annotate | Notes | Send | Clear | Minimize

Annotate

Turns element inspection/annotation on or off. Hover the page to inspect an element, then select it to create an annotation.

Notes

Shows your current annotations as a navigator. Choosing a note focuses its target and opens the note editor beside that element.

The contextual editor provides actions for:

• saving the note;
• opening Draw;
• opening Source;
• completing the annotation;
• deleting the annotation.

Long notes wrap vertically. The editor grows until its maximum height and then scrolls vertically.

Send

Builds an incremental change packet from the annotations that are new or changed since the previous handoff. The packet keeps source ownership, written instructions, Draw actions, placed-component intent, and visual evidence together.

When the detected IDE exposes a verified image-capable handoff, Skopeo can attach marked-up screenshots, original screenshots, and pasted references directly. Visual attachments are validated and budgeted fairly across annotations instead of silently allowing one annotation to consume the whole image limit. If direct IDE handoff is unavailable, Skopeo keeps the context usable and falls back safely.

Clear

Clears the active annotation session after the normal confirmation/state rules are satisfied.

Minimize

Collapses the primary toolbar without destroying the current session.

Source / Changes

The right-side inspector has two tabs.

Source

Shows source ownership for the active annotation when Skopeo can resolve it. Depending on the framework and confidence available, this can include:

• source file, line, and column;
• owning component/function;
• markup ownership;
• styles affecting the target;
• state/hooks or behavior ownership;
• related files and structural relationships;
• exact, high-confidence, ambiguous, or unresolved status.

File rows are clickable. Skopeo opens the resolved file/location in the current VS Code-compatible IDE, not a separate hardcoded editor.

Changes

Shows annotation changes and lets you focus the related target/source context without opening another note editor unnecessarily.

Moving the inspector

Drag the grip in the Source / Changes header to move the expanded inspector. When collapsed, the slim rail snaps back to the right edge of the viewport. Expanding restores the last expanded position.

Skopeo also tries to position contextual editors around other visible Skopeo panels instead of covering them.

When the inspected UI is inside an active modal, dialog, drawer, sheet, or similar overlay, Skopeo keeps its controls inside the same interaction boundary so common outside-click and focus-dismiss behavior does not close the host UI while you use Notes, Source / Changes, or other Skopeo controls.

Annotation rail and shortcuts

When Annotate is active, the left rail shows interaction state, multi-select state, selected target count, and shortcut help.

Default preview shortcuts:

Choose Customize shortcuts to change the configurable keys. The picker uses a compact key grid, prevents duplicate assignments, and applies changes immediately.

The bottom-right eye control hides or restores Skopeo's browser UI without discarding the active session.

Draw

Draw is for requests that are easier to explain visually than with text alone. It supports:

• freehand drawing;
• arrows and shapes;
• text;
• pasted image references;
• layer ordering;
• placed component previews;
• component appearance/contrast controls.

The managed component preview libraries are for visual specification. Installing or updating a Skopeo preview library does not install that UI library into your application.

Project scope

If the opened workspace contains multiple project folders, use Skopeo: Change Project Scope to choose which project Skopeo should inspect and associate with generated context.

Source navigation is restricted to real files inside the selected workspace/project root. Path traversal and symlink/junction escapes are rejected.

Commands

Open the Command Palette and search for Skopeo:

• Skopeo: Start — start Skopeo services for the current workspace.
• Skopeo: Stop — stop the active Skopeo session/services.
• Skopeo: Change Project Scope — choose the project Skopeo should use in a multi-folder workspace.
• Skopeo: Check for Updates — check the stable Skopeo distribution for a newer VSIX.
• Skopeo: Report a Bug — open the Skopeo bug-report workflow.

Settings

Useful stable settings include:

• visualAIBridge.runtimePort — preferred local Skopeo preview/bridge port. If occupied, Skopeo can move to another available port.
• visualAIBridge.agentMode — choose the handoff behavior such as IDE chat, clipboard, generate-only, or terminal command.
• visualAIBridge.chatCommand — optional IDE command ID used for direct chat/agent handoff.
• visualAIBridge.attachImagesToAgent — attach screenshots and visual references when the detected IDE exposes a verified image-capable handoff. A user-level false is authoritative and cannot be re-enabled by workspace settings. Disable this to keep image pixels out of direct AI submissions while retaining textual/source/visual-spec context.
• visualAIBridge.terminalCommand — terminal command template used when terminal handoff is selected.
• visualAIBridge.htmlLimit — maximum sanitized HTML characters captured per annotation.
• visualAIBridge.checkForUpdates — enables the stable manual-VSIX update check.

Security and privacy

Skopeo is designed for local development previews.

• Preview targets are restricted to HTTP loopback hosts such as localhost, 127.0.0.1, and ::1.
• The Skopeo runtime proxy binds to 127.0.0.1 rather than a public network interface and rejects unexpected HTTP Host headers. IDE-forwarded previews admit only the exact browser-facing origin resolved by the IDE.
• The browser runtime WebSocket uses a per-session token and checks the request origin before accepting the Skopeo runtime connection.
• Generated visual context is written locally to .ai-context/ in the selected project when you generate/send context. Secret-like URL parameters and DOM attributes such as tokens, API keys, passwords, session identifiers, and authorization values are redacted from generated text context when recognized.
• Captured page text, DOM/HTML, attributes, URLs, CSS, screenshots, and source excerpts are marked as untrusted evidence in generated AI instructions. Text displayed by the inspected application is never treated as authority to instruct the coding agent.
• In VS Code Restricted Mode, Skopeo does not execute workspace-controlled terminal handoff templates or custom agent command settings. Those execution paths require a trusted workspace.
• Screenshot capture prefers the actual rendered pixels of an installed Chrome, Microsoft Edge, or Chromium browser through a Skopeo-owned, loopback-only DevTools Protocol session. Skopeo launches that preview with an isolated temporary browser profile, does not open the DevTools UI, suppresses only Skopeo-owned controls for the capture frame, and cleans up the temporary profile when the managed preview stops. If native capture is unavailable or disabled with visualAIBridge.nativeScreenshotCapture, Skopeo automatically uses its existing bounded DOM-rendering screenshot fallback.
• Screenshot pixels cannot be meaningfully secret-redacted from the image itself. If a preview contains sensitive visible data, disable visualAIBridge.attachImagesToAgent or remove/redact that data before sending. Text/URL redaction remains separate defense in depth.
• Source navigation validates real paths and refuses files that escape the selected workspace/project root.
• Code Intelligence cache/state is kept outside the inspected repository.
• Skopeo does not require a Skopeo account or hosted Skopeo backend for the normal annotation workflow.
• Component-library and update downloads do not intentionally upload your project source, annotations, screenshots, DOM/CSS context, or generated .ai-context/ back to the distribution repository.

Treat .ai-context/ like any other generated development artifact: review it before sharing or committing it if your annotations or screenshots contain sensitive information.

Supported environments

Skopeo 0.1.32 is release-verified for Windows x64. A packaged stable VSIX is independently exercised on clean-profile Windows IDE hosts, including Kiro and Antigravity, while native screenshot capture is additionally exercised against a real installed Microsoft Edge browser. macOS, Linux, ARM64, WSL/SSH/Dev Containers, and other remote extension-host environments are not yet claimed as release-verified.

For environments that expose a local development server through IDE-managed forwarding, Skopeo resolves the browser-facing preview URI through the IDE when that API is available, while keeping the original target restricted to loopback HTTP development.

The preview workflow is built for local HTTP development servers. Exact runtime provenance remains strongest where framework DEV metadata is available, including React/Vite and Next.js client-side paths. Angular DEV ownership can use validated component debug metadata and external templates. Server-rendered Astro/React and additional stacks can use bounded route/import, visible-text, DOM-structure, and source-graph evidence; Skopeo keeps ambiguous or unresolved results explicit when exact ownership cannot be proved.

The native graph-enrichment host bundled with the current stable package is verified for Windows x64 and checked against Skopeo's bundled host-integrity manifest before execution. If the host is missing, invalid, or cannot start, Skopeo continues with exact runtime provenance and bounded heuristic source resolution instead of failing the annotation workflow. Other operating systems and remote extension hosts remain unverified in 0.1.32.

Troubleshooting

Preview does not open

Confirm your development server is running and that the URL is an HTTP loopback URL, for example http://localhost:5173. HTTPS and remote/public hosts are not accepted as normal Skopeo preview targets.

Port is already in use

Skopeo tries subsequent ports when the preferred runtime port is occupied. You can also change visualAIBridge.runtimePort in Settings.

Source is unresolved

The annotation remains usable even when exact source provenance is unavailable. Source Structure may show a high-confidence, ambiguous, or unresolved state instead of claiming an exact file incorrectly.

Source file does not open

Make sure the project scope is correct and the resolved file still exists inside the selected workspace. Source navigation intentionally refuses outside-workspace paths.

Automatic runtime injection is blocked

A strict Content Security Policy can prevent automatic runtime injection. Skopeo reports this instead of silently weakening the page policy; use the development-only manual injection guidance shown by Skopeo for that application.

Direct AI handoff is unavailable

Skopeo re-queries the running IDE's live command registry on every Send. Kiro and Antigravity integrations are host-scoped so another extension cannot win merely by registering a familiar command namespace. If an IDE update removes a known prompt command, Skopeo attempts a safe first-party replacement and otherwise falls back without marking the handoff sent.

Generated context remains local and usable. Switch the handoff mode or use the copy/generate workflow supported by your IDE.

Updates

Registry installations from the VS Code Marketplace or Open VSX use the IDE's normal extension update mechanism. Manual VSIX installations can use Skopeo: Check for Updates and the stable download provided by the Skopeo distribution page. Registry availability can lag the direct GitHub stable VSIX.

License

MIT