theORQL for VS Code (BETA)

Debug in Chrome, fix in VS Code—the only extension that captures runtime context in your browser, explains errors in plain language, and syncs validated fixes back to your editor.

Why developers install theORQL

• Faster debugging: Automatic capture of runtime errors, network requests, and console history ends console.log hunts.
• Cleaner pull requests: Catch runtime regressions locally with validated patches before review, so PRs land with fewer red flags.
• Chrome ↔ VS Code sync: Preview fixes in Chrome, then apply or revert the validated patch inside VS Code with one click.
• Runtime-aware AI guidance: theORQL’s built-in agentic AI (100 messages/month included in this beta) analyzes full runtime context to explain errors and suggest patches. You can optionally plug in your own AI API if you prefer a different model.
• DevTools-free workflow: Agentic chat explains the “why” behind errors without ever opening DevTools.
• Deployment & Production Integration Coming Soon: Connect theORQL to your deployment and CI pipeline so you can debug failures the same way you debug local runtime errors:
  • Vercel & Netlify deployments for build and runtime failures with full logs and runtime state.
• CI Pipeline Integration Coming Soon:
  • GitHub Actions workflows for CI pipeline error triage with AI explanations and validated fixes.
• Team Features Coming Soon: Invite teammates, chat in real-time in VSCode or Chrome, assign issues, and sync with GitHub/Jira when you are ready to scale.

Installation & Setup

Prerequisites

• Visual Studio Code 1.105.1 (macOS, Windows, or Linux).
• Google Chrome or Chromium-based browser v118+.
• theORQL’s own advanced, agentic 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 theORQL replacing tedious log hunting!

   • Browse your app. When a runtime error occurs, theORQL captures full context and surfaces explanations and validated fixes.

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: Resolve your first runtime error 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. Trigger an error
   • Navigate to a page or action that throws a runtime error. theORQL captures it instantly with full context.
4. Understand the root cause
   • theORQL parses stack traces, console history, and network state and explains the bug in plain language in Chrome and VS Code.
5. Preview a fix, then 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.
6. Commit and move on
   • Commit the change. If you linked GitHub/Jira, theORQL can update or link the issue.

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 this run in production?
This beta is primarily built for local development and dev-like environments (dev/staging). It’s not a full production monitoring or observability platform.

Do I need my own AI subscription?
No. theORQL includes its own advanced, agentic AI with 100 messages per month in this beta. 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.

theORQL does not send your data to any other services or additional AI vendors beyond:

• The models used to provide theORQL AI itself, and
• Any custom AI API endpoints you explicitly configure.

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.