OKAI Code Assistant — VS Code Extension

Autonomous AI coding agent inside VS Code. Assess, plan, implement, and verify code changes — directly in your sidebar, powered by a full ReAct loop with a local SLM by default and your choice of online model when you want one.

What it does

Plan tracking	Tool execution

🚀 Just installed from the Marketplace? Start here.

You have the extension. Now you need the OKAI backend running locally — it does the AI work and stores findings.

Step 1 — Install Docker Desktop (one-time)

If you don't have it: https://www.docker.com/products/docker-desktop/

Step 2 — Run the OKAI backend

docker run -d --name rag-okai -p 8000:8000 \
  -e NEO4J_PASSWORD=test12345 \
  okkarkp/rag:allinone

Step 3 — Verify (wait ~30s for the model to load)

curl http://localhost:8000/readyz

A 200 OK response means you're ready. Click the ⚡ OKAI bolt in the Activity Bar to open the chat — the status line will show OKAI: ready.

Tip: Run OKAI: Open Walkthrough from the command palette (Cmd+Shift+P / Ctrl+Shift+P) for the full guided setup including hosted-backend and build-from-source options.

⬇️ Alternative: Install via Docker (no Marketplace needed)

If you'd rather not use the Marketplace, the VSIX is bundled inside the Docker image — no GitHub or Marketplace access required.

Once the backend is running, download from:

http://localhost:8000/downloads/okai-latest.vsix

# One-liner install (backend must be running)
curl -fL http://localhost:8000/downloads/okai-latest.vsix -o okai-latest.vsix
code --install-extension okai-latest.vsix

If your backend is deployed on a different host, replace localhost:8000 with your server address.

❓ FAQ

--- The extension is a thin client to the OKAI analysis backend; all the heavy work (capability probe, pre-flight diagnostic, agentic troubleshoot loop, Rule 7 confidence scoring) runs server-side in Python.

Features

M1 — Read-only investigation

• Right-click "Find Root Cause for this Stack Trace" on any selection that looks like an error log or stack trace
• Findings tree view in the activity bar, grouped by HIGH ★ / TENTATIVE ◇ confidence
• Problems panel + editor squigglies for every finding's affected file:line
• Hover tooltip showing the full root_cause_chain (symptom → proximate → root)
• Status bar badge with finding count and detected diagnostic tools (git, dotnet, mvn, tsc, ng, …)
• Mark as false positive to remove a finding and report feedback to the backend
• TENTATIVE findings auto-prefixed in the title with severity downgraded one level — the Rule 7 "I don't know" path keeps low-confidence guesses out of your face

M2 — Apply fixes

• Lightbulb quick-fix on any line with a RAG diagnostic — choose "Generate fix for…", "Open all evidence files", or "Mark as false positive"
• Generate and Apply Fix command (also on every tree-view finding) — calls the backend's fix generator and shows a side-by-side diff
• Diff preview uses VS Code's native diff editor: original on the left, proposed content on the right, served from a virtual rag-fix: URI
• Apply / Discard prompt — Apply uses WorkspaceEdit so the change goes through VS Code's undo stack; complex operations fall back to the backend's apply-fix writer
• Verify-after-apply — the extension automatically re-runs the project diagnostic via /assess-agent/verify and surfaces:
  • ✓ "fix verified — diagnostic now clean"
  • ✗ "fix did not resolve the issue. Re-investigating may be needed."
• Tree view fix state — every finding shows its lifecycle in the title: ⏳ generating → 📝 proposed → ▶ applied → ✓ verified / ✗ failed. Verified findings turn green; failed ones turn red.

Installation

📖 Full setup guide — Docker configuration, LLM providers, authentication, CI/CD integration: SETUP.md

The intended distribution is Docker-only — no Node, npm, or vsce required on your machine. Three paths in order of recommendation:

Option A — Download the prebuilt VSIX from GitHub Releases (easiest)

CI runs on every release tag and attaches the .vsix to the release.

# Replace v0.1.0 with the latest release tag from
# https://github.com/okkarkp/rag/releases
curl -fL -o rag-troubleshoot.vsix \
  "https://github.com/okkarkp/rag/releases/download/v0.1.0/rag-troubleshoot-0.1.0.vsix"
code --install-extension rag-troubleshoot.vsix

Then start the backend with the bundled compose (next section).

Option B — Build the VSIX inside a one-shot Docker container

When you can't reach GitHub Releases or want to build from a specific branch, use the bundled Dockerfile.vsix-builder — it requires nothing but Docker on the host.

git clone https://github.com/okkarkp/rag.git
cd rag

# Build the VSIX inside Docker, copy the .vsix to your host
docker build -t rag-vsix-builder \
  -f vscode-extension/Dockerfile.vsix-builder vscode-extension

docker run --rm -v "$PWD":/out rag-vsix-builder \
  sh -c "cp /work/*.vsix /out/"

code --install-extension rag-troubleshoot-*.vsix

The builder image is throwaway (docker rmi rag-vsix-builder after) — its only job is to produce the .vsix file. No Node or npm touches your host.

Option C — Backend hosted elsewhere (corporate / shared deployment)

If your team already runs the backend, just install the VSIX from Option A or B and point the extension at the deployment:

// ~/.vscode/settings.json or workspace settings
{
  "rag.backend.url": "https://rag.your-company.com",
  "rag.backend.apiKey": "<token-from-RAG-admin>"
}

Starting the backend (after VSIX is installed)

If you don't already have a backend deployment, run the slim compose bundled with the extension:

cp vscode-extension/.env.example vscode-extension/.env
# Edit .env — set ANTHROPIC_API_KEY (or OPENAI_API_KEY), pick RAG_PROJECTS_DIR

docker compose -f vscode-extension/docker-compose.yml up -d
# Or for a fully local LLM (no API keys needed):
docker compose -f vscode-extension/docker-compose.yml --profile local-llm up -d
docker exec rag-ollama ollama pull llama3.1:8b

The compose launches:

• rag-backend (FastAPI on :8000) — the analysis engine
• rag-ollama (Ollama on :11434, only with --profile local-llm) — bundled local LLM so you don't need API keys

Architecture — local execution + remote AI

┌──────────────────────────────┐         ┌────────────────────────────────┐
│    Developer's PC            │         │   Docker backend               │
│                              │         │                                │
│  VS Code + this extension    │         │   FastAPI on :8000             │
│   • probe local toolchain    │         │   • LLM / RAG / parsing        │
│   • run dotnet build, etc.   │  HTTPS  │   • Rule 7 confidence scoring  │
│   • parse compile errors     │ ──────► │   • Pre-flight diagnostic      │
│   • git blame / git log      │         │     (fallback when client      │
│   • use REAL SDK + cache     │ ◄────── │      doesn't ship signals)     │
│   • use REAL secrets / feeds │  SSE    │   • run_shell / run_diagnostic │
│                              │         │     (fallback only)            │
└──────────────────────────────┘         └────────────────────────────────┘
            ▲
            │
        Your code, your SDK, your env

The split is intentional:

• Compile/typecheck/test commands run on the developer's PC because that's where the real .NET SDK / JDK / Maven cache / dotnet user-secrets / internal NuGet feeds live. The extension uses Node's child_process with strict argument tokenisation, no shell expansion, and a per-tool timeout.
• AI/RAG/analysis runs in the Docker backend because that's where the LLM context, the lineage graph, and the troubleshoot agent live — no need to bundle every language SDK into a container image.
• Compile errors flow as static_signals in the troubleshoot request, so the backend's LLM sees the bug stated in plain text from the developer's real environment in its very first prompt.

The rag.execution.mode setting controls this:

• auto (default) — run locally if a toolchain is detected, fall back to the backend's run_diagnostic
• local — always run on the developer's PC (refuse to fall back)
• container — never run locally, only the backend's bundled tooling

Enterprise security and observability

This extension is built for production use, not a proof of concept. Every interaction with the backend and the user's filesystem is auditable, retryable, and credential-aware.

Credentials — system keychain

rag.backend.apiKey is stored in VS Code's SecretStorage, which writes to:

• macOS: Keychain
• Windows: Credential Manager
• Linux: libsecret (gnome-keyring / KWallet)

The token is never persisted to plain settings.json. On first activation, any pre-existing plain-settings key is automatically migrated into SecretStorage and the plain entry is cleared. Use RAG: Sign In / RAG: Sign Out to manage credentials.

Request correlation

Every backend call carries an X-Request-Id header (UUID v4). The same id appears in the structured logs (RAG: Show Logs opens the LogOutputChannel) and in the backend's request logs, so support can correlate a user-reported issue to the exact session in seconds.

Audit log

Every meaningful action — session start/complete, finding emitted/displayed, fix generated/applied/verified/failed, false-positive mark, secret-scrub event — is appended to a JSONL file under VS Code's globalStorageUri. The file rotates at 10 MB (3 generations kept). Open with RAG: Show Audit Log.

Sample record:

{
  "timestamp": "2026-04-28T15:34:12.412Z",
  "action": "fix_verified",
  "finding_id": "abc",
  "files": ["src/Foo.cs"],
  "duration_ms": 54200
}

The audit log:

• never contains secret values (only the names of patterns that triggered scrubbing)
• never contains the API key
• is human-readable for compliance review
• survives across workspace switches (lives under user-global storage)

Secret + PII scrubbing

Findings can surface literal secrets when the LLM quotes from source files. Before any finding is shown in the diagnostics panel, hover, or tree view, every string field (title, description, code_snippet, root_cause_chain[], recommendation, fix_hint) is run through a regex scrubber that redacts:

• OpenAI / Anthropic / Stripe / Slack / Google API keys
• GitHub PATs (classic + fine-grained + app)
• AWS access + secret keys
• JWT tokens
• password=… / secret:… assignments (key visible, value redacted)
• Connection-string passwords
• -----BEGIN PRIVATE KEY----- blocks
• Authorization: Bearer … tokens

False positives are accepted (better to redact a long random string that wasn't a secret than surface a real one). The scrubber runs on the display copy only — the underlying file content the LLM reads is never modified.

Crash boundary

Every command handler is wrapped in withCrashBoundary(name, services, fn) so an unexpected exception:

• is logged with the full stack via the structured logger
• is recorded as a crash audit entry (handler name + error name/message + first 6 stack frames)
• surfaces a "RAG: <handler> failed — <short message>" notification with a "Show Logs" button

This replaces VS Code's red "extension host crashed" banner — users see something actionable, support can correlate the crash with a request id, and the extension stays alive for the next command.

Bundle

The shipped .vsix contains a single 105 KB bundled file (out/extension.js) produced by esbuild, not the ~33 unbundled .js + .map files a plain tsc build would produce. This makes the VSIX 47% smaller and activation noticeably faster on cold start. Source maps stay enabled so stack traces still resolve to original .ts lines.

Persistent feedback queue

When you mark a finding as a false positive or a fix succeeds/fails, the feedback POST to the backend is durable: persisted to globalStorageUri/feedback-queue.jsonl, retried on activation, and after every minute of background flushing. Exponential backoff (1s → 5min) on transient failures, dropped after 8 attempts. Use RAG: Flush Pending Feedback Queue to force a flush.

Retry and backoff

Every non-streaming backend call (capabilities, feedback, apply-fix, etc.) retries up to 3 times on:

• HTTP 429 (rate-limited)
• HTTP 5xx (server errors)
• network errors

Exponential backoff (500ms → 30s). 4xx responses (other than 429) are returned immediately as BackendError with a structured category (AUTH | RATE_LIMIT | SERVER | NETWORK | CLIENT | UNKNOWN).

Structured logging

RAG: Show Logs opens a VS Code LogOutputChannel with per-line metadata:

2026-04-28 15:34:12.412 [info] [api.troubleshoot] rid=a1b2c3d4 stream open {"project_path":"/repo","static_signals_count":3}

The user controls the level via the gear icon in the Output panel (trace / debug / info / warn / error). Set to "trace" when filing a support ticket.

Configuration

Usage

1. Paste a stack trace into any editor (or open a log file).
2. Select the trace text (multi-line is fine).
3. Right-click → "RAG: Find Root Cause for Selected Stack Trace" (or Ctrl+Shift+P → same command).
4. Enter a one-line problem description in the input box (e.g. "POST /orders returns 500 NullReferenceException").
5. Watch the progress notification stream phase / tool / finding events.
6. When done, the findings panel opens automatically; entries appear in Problems and as squigglies in the editor; hover for the full causal chain.

The status bar shows live progress while running and a summary (★3 ◇1 · git/dotnet) when idle. Click it to open the panel.

What the extension expects from the backend

• POST /assess-agent/troubleshoot/stream — SSE endpoint emitting phase, tool_call, finding, done, error events
• GET /assess-agent/capabilities?project_path=… — returns the host + project capability probe (git, dotnet, mvn, ng, tsc, eslint, …)
• POST /assess-agent/finding/feedback — records "false positive" / "fix worked" feedback

These are all defined in backend/assess_agent_api.py and ship with the bundled Docker image.

Troubleshooting

• "backend unreachable" in the status bar → check rag.backend.url; the default assumes the backend is on localhost:8000. If you used docker compose up, verify with curl http://localhost:8000/assess-agent/categories.
• Empty findings panel after a session → check the Problems panel; some findings may have line=0 (unknown line) and only show in the tree view, not as squigglies.
• All findings rejected with low confidence → the host may be missing diagnostic tools (dotnet / mvn / tsc). Check the status bar tooltip — if no tools are listed, run_diagnostic can't run and confidence scores stay low. Install the toolchain or accept lower-confidence findings via rag.confidence.minDisplay = "ALL".

Roadmap

This is the M1 release — read-only.

• M2 — Apply fixes via diff preview + verify-after-apply loop calling run_diagnostic again ✓ shipped
• M3 — Chat panel with /troubleshoot, /blame, /diff, /test, /diagnostic slash commands; inline ghost-text shortcuts for trace_call_chain
• M4 — LSP server bridge so JetBrains, Neovim, Sublime can use the same backend

See docs/vscode-plugin-design.md in the parent repo for the full design.

Development workflow

Local dev requires Node 20 (the version VS Code 1.85+ ships with) and Docker is not needed for the extension itself — only for running the backend. From a fresh clone:

cd vscode-extension
npm install            # also installs the husky pre-commit hook
npm run compile        # tsc -p .  → out/
npm run lint           # ESLint with @typescript-eslint + security rules
npm run format         # Prettier auto-format every .ts / .json / .md
npm test               # Vitest unit suite (163 tests, ~2s)
npm run test:integration  # Real VS Code window via @vscode/test-electron
npm run package        # Build .vsix for distribution

Pre-commit hook

husky + lint-staged runs only on staged files so a typo in one module doesn't lint the whole repo:

git add src/foo.ts
git commit -m "..."
# → husky runs lint-staged →
#    eslint --fix src/foo.ts  (auto-fix what it can)
#    prettier --write src/foo.ts  (reformat to project style)
# → if eslint reports errors, commit is BLOCKED

To bypass (rarely needed): git commit --no-verify. CI re-runs the same checks regardless.

Editor setup

.editorconfig configures every editor (VS Code, JetBrains, Vim, Emacs) with our indentation/EOL/charset settings. VS Code users should also install the Prettier and ESLint extensions to get save-on-format and inline lint warnings — both respect our .prettierrc.json / .eslintrc.json automatically.

Lint policy

• @typescript-eslint/recommended baseline + eslint-plugin-security for the regex-heavy modules
• Errors block CI: bad equality, undefined globals, unsafe regex, etc.
• Warnings allowed up to 50 (currently ~39, mostly no-floating-promises on vscode.window.show*Message calls — explicit void markers can be added incrementally)
• Test files relax no-floating-promises (vitest fixtures throw synchronously)

Running tests

The extension has unit tests for its parser and store logic — run before any non-trivial change:

cd vscode-extension
npm install
npm test            # one-shot
npm run test:watch  # re-run on save

CI runs npm test before packaging the VSIX, so a failing test blocks release.

Coverage targets the most fragile code:

UI-touching code (commands, providers, status bar) is exercised through a minimal vscode shim at test/__mocks__/vscode.ts that stubs only the surfaces our code touches at module-load time.

Integration tests (real VS Code instance)

@vscode/test-electron launches a real VS Code window with the extension loaded and runs Mocha tests inside it. The full troubleshoot → diff → apply → verify flow is exercised against an in-process fastify mock backend so the tests need no external service.

cd vscode-extension
npm install
npm run test:integration   # downloads VS Code if not cached, runs the suite

Coverage:

Each test starts a fresh fastify mock on an ephemeral port (mockBackend.ts) and points rag.backend.url at it. Tests inspect state through the Services container that activate() returns.

CI requirement: Linux runners need an X server. The CI step is:

- name: Run integration tests
  run: |
    sudo apt-get install -y xvfb
    xvfb-run -a npm run test:integration
  working-directory: vscode-extension

macOS and Windows runners run npm run test:integration directly — no Xvfb needed.

Enterprise Readiness Checklist

The one-click install link below is only published once every item below is ✅. This protects users from installing an unstable build into production environments.

✅ Done

🔲 Required before public download link is live

Once all 🔲 items are checked off, uncomment the install section below.

Q&A

# Create a docker-compose.allinone.yml (or download from the repo):
docker pull okkarkp/rag:allinone

# Or with docker compose (recommended — handles volumes and restarts):
curl -fsSL https://raw.githubusercontent.com/okkarkp/rag/main/docker-compose.allinone.yml \
  -o docker-compose.allinone.yml

docker compose -f docker-compose.allinone.yml up -d

curl http://localhost:8000/readyz
# → {"status":"ok"}

curl -fL http://localhost:8000/downloads/okai-latest.vsix -o okai-latest.vsix

code --install-extension okai-latest.vsix

/generate create a ProductController with full CRUD using EFCore and async/await

/assess Controllers/ProductController.cs

/explain Controllers/ProductController.cs

/test Controllers/ProductController.cs

/ask what design pattern is used in this project?

/findings
/fix 1

● Thought for 26s ›
  I need to check whether the Student entity exists before
  creating the controller. I'll list the Entities folder first...

docker pull okkarkp/rag:allinone

docker compose -f docker-compose.allinone.yml up -d

docker compose -f docker-compose.allinone.yml down

docker compose -f docker-compose.allinone.yml logs -f

docker compose -f docker-compose.allinone.yml up -d

docker pull okkarkp/rag:allinone
docker compose -f docker-compose.allinone.yml down
docker compose -f docker-compose.allinone.yml up -d

curl -fL http://localhost:8000/downloads/okai-latest.vsix -o okai-latest.vsix
code --install-extension okai-latest.vsix --force

# .env
LOCAL_LLM_URL=http://192.168.0.17:14336   # e.g. your own llama-server with a 7B model