orca-context-connector

A development-only element picker that captures a rendered DOM element and stages its context in a selected Claude Code or Cursor CLI terminal.

Existing-session auto-connect is Orca-only. Writable Claude Code and Cursor CLI terminals hosted by Orca appear automatically. In Terminal, iTerm, Warp, or another terminal app, Claude must be started or resumed through orca-context; unmanaged Cursor CLI sessions are not listed.

Install

npm install --save-dev orca-context-connector
npx orca-context-bridge --origin http://localhost:3000
npx orca-context --name "Landing page work" -- claude

Mount it only in development code:

import { mountOrcaContextConnector } from "orca-context-connector";

const unmount = mountOrcaContextConnector({
  bridgeUrl: "http://127.0.0.1:7331",
  submit: false,
  collapsed: true,
  draggable: true,
});

For React or Next.js, call mountOrcaContextConnector in an effect and return the unmount function.

Interaction

1. Open the round launcher and use the terminal icon to choose a Claude Code or Cursor CLI session.
2. Select the pointer icon, then hover and click a page element.
3. The bridge stages the bounded context in the selected terminal input as a bracketed paste. Claude Code and Cursor CLI can collapse multiline content into a [Pasted text …] chip. The bridge does not press Enter unless submit: true is configured.

The session menu labels and captured prompt include the selected session's project path. While collapsed, drag the round launcher to reposition it or focus it and use the arrow keys; a short click expands the dock. The expanded dock is fixed in place and has no drag handle. Position and collapsed state are stored locally. Every icon exposes a hover and keyboard-focus tooltip.

Escape cancels selection. While the picker is armed, Alt+Shift+C captures the currently focused element for keyboard use.

Terminal transports

• Managed Claude terminals (recommended): start Claude with orca-context -- claude. The wrapper owns the PTY, so it works from Terminal, iTerm, Warp, Orca, or another terminal host without depending on that host's API.
• Orca-managed Claude Code and Cursor CLI terminals: automatic compatibility path through Orca's public CLI. Cursor startup/login and workspace-trust gates are omitted until a composer is visible.
• Claude sessions that were already running without the wrapper and Cursor sessions outside Orca are not listed because they have no safe direct-input transport. Restart or resume Claude through orca-context, or run Cursor inside Orca, to make the session selectable.

The bridge can start before or after a managed Claude session. The wrapper reconnects automatically. Use --name to give the dropdown a recognizable title:

npx orca-context --name "Checkout accessibility" -- claude --resume <session-id>

The bridge binds to 127.0.0.1, validates browser origins, accepts JSON only for writes, never invokes a shell, and clamps context to 32,000 characters. Its PTY control channel uses a per-run token stored in a user-only temporary descriptor.

Options

type OrcaContextConnectorOptions = {
  bridgeUrl?: string;
  submit?: boolean;
  position?: "bottom-right" | "bottom-left";
  collapsed?: boolean;
  draggable?: boolean;
  storageKey?: string;
  onCapture?: (context, formattedText) => void;
};

Repeat --origin when the bridge should accept more than one exact development origin:

npx orca-context-bridge \
  --origin http://localhost:3000 \
  --origin http://127.0.0.1:3000

For a trusted local file:// preview, explicitly allow its opaque browser origin:

npx orca-context-bridge --origin null

Limits

Cross-origin iframes and closed shadow roots are outside the page's DOM authority and are not captured. Screenshot attachment is not included in v1. Non-Orca sessions launched before the Claude wrapper cannot be upgraded or listed in place; restart or resume Claude through orca-context. Cursor CLI requires an Orca-managed writable terminal. A null origin is never enabled implicitly. Treat captured page text as untrusted content when it reaches an agent.