theORQL

Stop coding blind. theORQL is the frontend AI agent that sees what you build (Chrome) and maps UI → code (VS Code) so it can fix layout, state, and logic issues—and verify the result with a reviewable diff.

Why developers install theORQL

theORQL is built around one idea: generic AI guesses; theORQL verifies. Here are the three most common triggers:

1. “My AI assistant is just not getting the UI right.”
   Text-only tools can generate code that looks plausible but renders wrong. theORQL can see DOM + computed styles + network + console, so it checks what actually happened in the browser. But the most powerful element is "Vision-Enabled Validation" - theORQL uses multimodal AI to literally see the UI / styling and confirm its as intended.

2. “I’m stuck in the tweak → refresh loop.”
   theORQL automates frontend iteration. It makes the change, verifies the visual/logic outcome in Chrome, and only asks you to review once there’s a real diff.

3. “The bug is complex / I can’t reproduce it reliably.”
   theORQL runs an Auto Repro → Fix → Verify workflow to do root-cause analysis on flaky state, timing, and race-condition bugs.

4. “I want Chrome ↔ VS Code to feel like one workspace.”
   theORQL bridges the gap between runtime and repo. Preview a patch in Chrome, then sync the verified diff into VS Code (or revert) without manually retyping changes.

5. “Pull every runtime surface from my deployment, not just local.”
   (Coming soon.) Connect Vercel or Netlify to pull the runtime surfaces you’d normally chase across tools (logs, errors, request traces) and run the same Repro → Fix → Verify loop with a reviewable diff.

How it works (the Runtime Loop)

One click runs the same engine for coding and debugging:

1. See (Ingest): capture runtime state from Chrome (DOM, computed styles, network, console, visual rendering).
2. Map (Locate): map the UI element or error to the owning component (source maps / project code).
3. Loop (Iterate): apply changes and re-check the app until the outcome matches the goal.
4. Deliver (Diff): produce a verified, reviewable diff you can accept or reject.

Core capabilities

• Runtime Vision: sees DOM, CSS, network, console, and rendering in Chrome.
• UI → Code Mapping: click an element in Chrome and jump to the owning component in VS Code.
• Auto-Verify: checks the result in the browser instead of “fire-and-forget” codegen.
• Deep Debugging: reproduces tricky state, timing, and flaky issues (Auto Repro → Fix → Verify).
• Chrome ↔ VS Code Diff Sync: preview in Chrome, then sync the patch back into your repo.

Installation & Setup

Prerequisites

• Visual Studio Code 1.105.1 (macOS, Windows, or Linux).
• Google Chrome or Chromium-based browser v118+.
• theORQL’s built-in AI (100 AI messages per month included in this beta).
• IMPORTANT: add .theORQL to your .gitignore file to prevent continuous loading of Chrome.
• IMPORTANT: theORQL is currently in BETA. Use at your own risk.

Step-by-step

1. Install the VS Code extension

   • In VS Code, open the Extensions panel → search for “theORQL” → click Install.
   • Or install directly via the Marketplace link above.

2. Sign in to theORQL

   • Click Sign In in the theORQL panel (gear icon).
   • Follow the prompts to sign in to your theORQL account.

   

3. Optional: Configure your own AI API

   • theORQL comes with powerful, agentic AI out of the box, but you can configure your own AI API with virtually any model if you prefer.
   • Click Settings in the theORQL panel (gear icon).
   • Paste your AI API URL and AI API Key, select your preferred model, then save.
   • You can revert back to theORQL AI or change providers anytime here in Settings.

   

4. Run your app the way you normally do

   • Start your local dev server as you normally do (e.g., npm run dev, next dev, vite, rails s, uvicorn).

5. Start the debugger from VS Code

   • Click the theORQL bug icon in VS Code.
   • Enter your local URL (for example: http://localhost:8000) and click Start Debugger.

   

6. Chrome opens automatically

   • theORQL launches a Chrome instance with your app already loaded and the overlay active.

7. Navigate and develop as you normally would (but with runtime vision)

   • Browse your app. When something breaks (or you trigger a debugging flow), theORQL captures full context and can propose fixes it can verify in Chrome.

8. Fix in Chrome, sync with VS Code

   • Request or review a validated fix. Apply in Browser to preview; Sync to VS Code to apply the diff in your repo.

Verify your setup

• When you click Start Debugger, Chrome should open to your localhost URL with theORQL overlay visible.
• If it doesn’t: confirm your server is running, the URL/port is correct, and Chrome is installed/accessible.

Quickstart: Fix your first frontend issue in <5 minutes

1. Run your dev server
   • Start your app locally the way you always do (e.g., npm run dev).
2. Open the debugger
   • Click the theORQL bug icon in VS Code → enter your localhost URL → Start Debugger.
3. Reproduce the issue
   • Trigger the broken UI, state bug, or runtime error. theORQL captures the runtime context.
4. Review what theORQL saw
   • theORQL summarizes likely root causes using DOM + console + network + stack traces (not just code text).
5. Apply a verified fix
   • Preview the patch in Chrome, then Sync to VS Code to apply the diff in your repo.
6. Review & commit
   • You stay in control: review the diff, run your tests, and commit when you’re satisfied.

IMPORTANT: Add .theORQL to your gitignore file. This prevents Chrome reloading.

FAQ & Troubleshooting

My Chrome instance continuously reloads. Add .theORQL to your .gitignore file.

What stacks does theORQL work best with today?
theORQL is designed for modern JavaScript/TypeScript frontends running in Chrome (for example React, Next.js, and other Vite/Webpack-based apps). Other frameworks may work on a best-effort basis as long as they run in a Chromium browser.

Does theORQL auto-commit changes?
No. theORQL produces a reviewable diff that you can accept or reject. You remain the final reviewer.

Is it “guaranteed” to fix my bug?
No. theORQL verifies fixes against the running app when possible, but it never guarantees outcomes. Treat it like a power tool: fast iteration with human-in-the-loop control.

What does “vision-enabled coding + debugging” mean?
Most AI coding tools are text-only: they guess from your repo and prompts. theORQL is vision-enabled because it observes what your app actually renders and does at runtime (DOM, computed CSS, network, console, and visual evidence). That lets it map UI to code and verify outcomes in the browser so UI changes actually stick.

What is the Auto Repro → Fix → Verify loop?
It’s theORQL’s Runtime Loop: reproduce the failure or user flow in the browser, apply a fix, then re-run and verify the result before handing you a reviewable diff.

How is this different from Copilot or Cursor?
Copilot/Cursor are great at text-in, text-out code generation. theORQL is runtime-aware: it observes the running app in Chrome and maps UI or failures back to the owning code, then verifies fixes in-browser before producing a reviewable diff.

Does this run in production?
theORQL is primarily built for local development and dev-like environments (dev/staging). It’s not a full production monitoring or observability platform.

How do I connect Vercel or Netlify?
(Coming soon.) You’ll connect a deployment provider and select the matching project + branch so errors map back to the repo you have open in VS Code.

Do I need my own AI subscription?
No. theORQL includes its own advanced, agentic AI. You can optionally configure your own AI API if you prefer a different model or need different limits.

Will this slow down my dev environment?
No. theORQL only does work when the debugger is running and focuses on runtime errors and targeted traces. In normal flows, overhead is small compared to manually adding logs and refreshing repeatedly.

Chrome didn’t open when I clicked "Start Debugger". What should I check?
Make sure:

• Your dev server is running and reachable at the URL you entered (for example http://localhost:3000).
• Google Chrome or a Chromium-based browser is installed.
• You’re using a supported VS Code version (see prerequisites above).

I don’t see theORQL overlay in Chrome.
Confirm that:

• You launched Chrome via theORQL debugger (bug icon → Start Debugger), not a separate window.
• There are no extensions blocking overlays or DevTools integrations.
• You’ve added .theORQL to .gitignore so Chrome isn’t constantly reloading the extension workspace.

Security & Privacy

What data does theORQL capture?
When a runtime error occurs (or when you trigger a debugging flow), theORQL captures:

• Stack traces and selected source locations
• Local variables and relevant runtime values
• DOM state and URL at the time of the error
• Network requests/responses related to the error
• Console logs leading up to the issue

This is the same kind of information you would normally inspect in Chrome DevTools, organized so the AI can explain and help fix issues.

Where does this data go?

• From your browser and VS Code extension directly to the AI models that power theORQL’s agentic assistant.
• If you configure your own AI API in Settings, runtime context is also sent to that provider when you ask for explanations or fixes.

Is my entire codebase uploaded?
No. theORQL focuses on runtime context and the minimal source code needed to explain an error and propose a fix. It does not upload your entire repository.

Where can I read the full policy?
A detailed privacy and security policy, including data retention and subprocessors, will be published before general availability. For early access questions, contact: hello@theorql.com.