Browser & VS Code extensions

Run Pellucid against any selection on any web page, or against any markdown file in your editor. Both extensions talk to the same API you call directly.

The browser extension lives in apps/extension/ as a Manifest V3 unpacked extension. The VS Code extension lives in apps/vscode/ and ships as a standard .vsix package. Neither needs auth today; both honour the user-configured API URL so you can point them at http://localhost:8000for dev or your deployment’s origin in production.

Browser extension

Adds a right-click Analyze with Pellucid entry to any text selection. Behind the scenes the service worker creates a document on the API, opens an SSE stream, reads the first rule_findings event, and renders a popup with the count + a deep link to the full analysis in the web app.

Install

1. Clone the Pellucid repo and run pnpm install.
2. Open chrome://extensions in Chrome, Edge, or Brave.
3. Toggle Developer mode on.
4. Click Load unpacked and select apps/extension/.
5. Pin the puzzle-piece icon so the popup is one click away.

Configure

Click the gear icon on the extension entry → Extension options. Set the API URL to wherever your Pellucid instance lives. The default ishttp://localhost:8000.

API URL:    http://localhost:8000
Web URL:    http://localhost:3000
Auto-open:  on   (jumps straight to /analyze/<id> after a scan)

CORS — the one backend change

Chrome loads the extension from chrome-extension://<id>/, which is not a default allowed origin. The shipped API config already handles this with allow_origin_regex=r"chrome-extension://.*" in apps/api/main.py, but if you tighten origins in production you’ll need to keep that regex (or pin to a specific extension id).

app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.cors_origins_list,
    allow_origin_regex=r"chrome-extension://.*",
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Use it

1. Highlight any text on any page.
2. Right-click → Analyze with Pellucid.
3. The popup shows a finding count within ~200 ms (rule layer). ClickOpen full analysis to jump to /analyze/<id> in the web app, where the agent layer continues to stream.

The extension uses an AbortController to close the SSE stream as soon as rule_findingsarrives — the popup never needs the agent events, so cancelling early saves bandwidth. LLM calls already in flight on the server will continue until they complete; that’s intentional and documented in apps/extension/INTEGRATION.md.

Troubleshooting

• CORS error in the service-worker console. Visit chrome://extensions → Pellucid → Service Worker → Inspect views to see the failing request. The fix is adding chrome-extension://* to PELLUCID_CORS_ORIGINS or keeping the default allow_origin_regex.
• Right-click entry doesn’t appear. The MV3 manifest requires contextMenus, scripting, and activeTab. Reload the extension after a code change via the ↻ arrow on its card.
• Selection comes back empty on a PDF/custom editor. The extension falls back to window.getSelection() via chrome.scripting.executeScript. If that’s blocked (e.g. the page is a Chrome internal URL), there’s no recourse — paste into the web app instead.

VS Code extension

Surfaces Pellucid findings as native vscode.Diagnostic objects — squiggly underlines in the editor, entries in the Problems panel, severity-coloured status bar item. Each diagnostic gets a Forge Clarity (rewrite) quick fix that calls the rewrite endpoint and applies the chosen candidate via a WorkspaceEdit.

Install

From source, for development:

cd apps/vscode
npm install
npm run compile      # tsc -p ./

# Then open apps/vscode in VS Code and press F5 to launch an
# Extension Development Host with the extension loaded.

To produce a redistributable VSIX:

npm install -g @vscode/vsce
cd apps/vscode
vsce package         # → pellucid-vscode-0.1.0.vsix

# Install the VSIX:
code --install-extension pellucid-vscode-0.1.0.vsix

Configure

Open VS Code settings (Cmd/Ctrl + ,) and search for pellucid. The relevant keys:

{
  "pellucid.apiUrl": "http://localhost:8000",
  "pellucid.runOn": "command"   // or "save" once the watcher lands
}

Use it

1. Open a markdown or plaintext file. The status bar shows Pellucid: idle.
2. Run Pellucid: Analyze Current File from the command palette (Cmd/Ctrl + Shift + P), or Analyze Selection if you only want to scan a block.
3. Diagnostics appear in the Problems panel and inline as squiggles. The status bar item updates with the count and severity colour.
4. Click any diagnostic in the gutter and pick Forge Clarity (rewrite). A QuickPick lists 2–3 candidates with rationales; selecting one applies the rewrite as aWorkspaceEdit.

Severity mapping

No CORS dance required

VS Code extensions run in the Node-based extension host, not a browser renderer, so fetchisn’t origin-restricted. No backend changes are needed to use the extension against any Pellucid deployment.

Current limits

• No live re-analysis.Diagnostics don’t refresh on edit; re-run the command after changes.
• One stream per file. Running Analyze twice in quick succession will start two streams; the second wins.
• Each run creates a new document. No persistence of documentId between runs (yet).

What the extensions actually call

Both extensions are pinned to the same minimal subset of the API. Useful if you’re building a third extension and want a known-good cross- section:

The full API is documented at /docs/api.