Al Hakeem Assistant - VS Code Extension

An agentic coding assistant extension for VS Code, powered by a C# backend. Supported engines:

• Llama.cpp (Strata: Console and not Desktop)
• vLLM
• Ollama
• LM STudio
• Lemonade
• Unsloth Studio

Architecture

The extension uses stdio JSON-RPC for communication with the C# backend:

1. VS Code Extension (TypeScript/Node.js) – Provides the UI (webview chat panel)
2. C# Host Process – Console app that wraps your backend DLL and speaks JSON-RPC over stdin/stdout
3. Your Backend DLL – The core AI/agentic logic

Quick Start

1. Install Extension from VS Code

1. Open the Extensions view in VS Code (Ctrl+Shift+X on Windows/Linux, or Cmd+Shift+X on macOS).
2. Search for Al Hakeem.
3. Select Al Hakeem by NaserHAlharbi, then select Install.

2. Download and Install Extension from Visual Studio Marketplace

Open the Al Hakeem extension page on Visual Studio Marketplace and select Install to open the extension in VS Code.

To install it manually, select Download Extension on the Marketplace page to download the .vsix file. In VS Code, open the Command Palette (Ctrl+Shift+P on Windows/Linux, or Cmd+Shift+P on macOS), run Extensions: Install from VSIX..., and choose the downloaded file.

3. Dependencies

.Net 8.0 Runtime: https://dotnet.microsoft.com/en-us/download/dotnet/8.0

You only need the .NET Runtime (No SDKs, No Desktop, No ASP.NET Core, just Runtime)

4. Run the Extension

In VS Code (Extension Development Host):

1. Open this folder in VS Code
2. Press Ctrl+Shift+D to open the debug panel
3. Click "Run Extension"

The extension will launch in a new VS Code window. The chat panel should appear on the right side.

Both user and assistant bubbles render Markdown, including code blocks, lists, tables, and Mermaid diagrams. Select bubble text and press Ctrl+C (Cmd+C on macOS) to copy the selection, or use the bubble's clipboard (📋) button to copy its original Markdown. The button appears on bubble hover or keyboard focus.

While the LLM is generating a reply or summary, Refresh Models, Select Model, View Chat History, Clear Chat, Settings, Summary, Shrink, and Attach are disabled. They become available again when generation finishes, fails, is cancelled, or immediately when you click STOP.

Loading a saved chat restores the bottom token and timing statistics from its last assistant message. Chats without saved statistics show zero values. The usage bar is blue below 50%, amber at 50-89%, and red at 90% or higher, based on the displayed percentage, for both live replies and saved chats.

Image Attachments

For llama.cpp image input, load a vision-capable model with its matching --mmproj projector, then refresh the model list and select a model marked with the eye icon. Attach an image using the chat attachment button, drag-and-drop, or paste. Files from Windows File Explorer can be dropped anywhere inside the chat pane; the message input highlights while dragging, and attachment chips appear before sending. Images require a vision-capable selected model. Each message accepts up to five attachments, at most 10 MB each. If Windows blocks dragging from File Explorer into VS Code running as administrator, run VS Code without elevation or use the Attach button.

Plain-text (.txt), Markdown (.md, .markdown), and PDF files can also be attached using the Attach button or drag-and-drop; they do not require vision. Plain-text files are read as text even when their MIME type is missing.

Run the attachment regression tests with node --test .\scripts\chat-attachments.test.js.

The backend sends images as image_url content parts alongside the user's text, with an explicit attachment count for each image-bearing message. The system prompt also describes image support for the selected model. A model's own claim that an image is missing is not a transport or capability check; local models can still generate incorrect refusals. After updating the backend, restart the extension development host to load the new build.

Project Structure

alhakeem-vs-code-extension/
├── src/
│   ├── extension.ts          # Main extension entry point
│   ├── backend/
│   │   └── connection.ts      # JSON-RPC stdio client
│   └── panels/
│       └── chatPanel.ts       # Webview panel logic
├── media/
│   ├── chat.css              # Webview styles (blue/dark theme)
│   ├── chat.js               # Webview client-side logic
│   └── icon.svg              # Extension icon
├── csharp-host/
│   ├── Host.csproj           # C# project file
│   └── Program.cs            # JSON-RPC host implementation
├── package.json              # NPM dependencies and scripts
├── tsconfig.json             # TypeScript config
└── README.md

JSON-RPC Protocol

The extension and backend communicate via line-delimited JSON-RPC 2.0:

Request (Extension → Backend)

{"jsonrpc":"2.0","method":"chat","params":{"message":"Hello","history":[...]},"id":"uuid-here"}

Response (Backend → Extension)

{"jsonrpc":"2.0","result":{"reply":"Response text"},"id":"uuid-here"}

Notification (one-way, no id field)

{"jsonrpc":"2.0","method":"log","params":{"level":"info","text":"Status update"}}

Supported Methods

chat (Request)

Params:

• message (string) – User query
• history (ChatMessage[]) – Conversation history

Response:

• reply (string) – Assistant response
• (add other fields as needed)

ping (Request)

Response:

• pong

UI Design

The extension provides a webview chat panel with:

• Blue user messages (accent: #0d47a1)
• Dark assistant responses (#2a2a2a)
• Responsive input field at the bottom
• Auto-scroll on new messages
• Timestamps for each message

The design matches the provided screenshot.

Debugging

Extension Debugging

Press F5 in VS Code to start the extension in debug mode. The extension host window will open.

Backend Debugging

Attach a debugger to the C# process:

1. Run the C# host with debugger support
2. Use Visual Studio or VS Code's C# extension to attach

Or print logs to stderr:

Console.Error.WriteLine($"[Debug] {message}");

These will appear in the "Debug Console" of the extension host.

Configuration

Setting	Type	Default	Description
alhakeem.useStdio	boolean	true	Use stdio JSON-RPC (stdio mode) or HTTP
alhakeem.backendPath	string	""	Path to C# host .exe (required for stdio mode)
alhakeem.backend.host	string	127.0.0.1	Backend hostname (HTTP mode)
alhakeem.backend.port	number	5000	Backend port (HTTP mode)

Extending the Extension

Browser mode (Settings > Tools)

Choose Built-in VS Code browser or External Chromium (separate window) in the chat Settings menu's Tools tab, then save and reload. The same choice is available as alhakeem.browser.mode in VS Code Settings. Built-in is the default; the extension never silently falls back to an external window.

Built-in VS Code browser: requires a VS Code build that exposes the proposed browser API and permission for NaserHAlharbi.alhakeem. No separate browser installation is required. Close all VS Code windows, then launch:

code --enable-proposed-api=NaserHAlharbi.alhakeem

For Insiders, launch with:

code-insiders --enable-proposed-api=NaserHAlharbi.alhakeem

Enable the built-in browser API permanently

1. Press Ctrl+Shift+P (macOS: Cmd+Shift+P) in the VS Code installation you use.

2. Run Preferences: Configure Runtime Arguments.

3. Inside the existing configuration's { }, add:

   "enable-proposed-api": ["NaserHAlharbi.alhakeem"]
   

   Separate existing properties with a comma. If enable-proposed-api already exists, add "NaserHAlharbi.alhakeem" to its array rather than adding a duplicate property.

4. Save the configuration, fully quit VS Code and close every window, then reopen it. Developer: Reload Window alone is not enough to apply changed runtime arguments. On macOS, use Code > Quit Visual Studio Code (or Cmd+Q).

5. In Al Hakeem, open Settings > Tools > Browser, select Built-in VS Code browser, and save. Reload the window if you changed browser mode.

6. Keep Al Hakeem: Use Stdio enabled and run Al Hakeem: Run Browser Smoke Test.

Insiders uses its own runtime configuration; perform these steps inside Insiders if that is the installation you use. No separate Chromium download is needed for built-in mode.

Permission cannot add an API that the build lacks. The settings selector cannot grant API permission itself. Copilot's first-party access does not automatically authorize other Marketplace extensions.

External Chromium: works in local desktop VS Code 1.90+ without proposed API permission. It opens a separate visible window only when this mode is selected. The browser uses an isolated, temporary profile; it never connects to users' personal Chrome/Edge sessions. Cookies and logins last only for the current extension session.

1. Keep Al Hakeem: Use Stdio enabled (reload after changing transport).
2. For external mode only, run Al Hakeem: Install Browser and approve the first-time Chromium download. Alternatively, the first browser request prompts for installation when Chromium is missing.
3. Enable the desired browser tools in the chat Settings panel.
4. Run Al Hakeem: Run Browser Smoke Test to check the local browser.

Chromium is downloaded from Playwright's distribution servers into its per-user browser cache, not bundled into the VSIX. Downloads can be several hundred MB; updates may require a new browser revision. Download output and launch errors appear in Output > Al Hakeem Browser. External mode on Linux requires Chromium system libraries and a graphical desktop. External tools are unavailable in web/remote windows. Both modes require stdio.

Sharing an existing browser tab requires consent. Use Al Hakeem: Revoke Browser Sharing to detach without closing the tab. New popups are not automatically shared. File uploads and each new restricted snippet require separate approval. Alert, confirm and prompt dialogs are handled through handleDialog. Native prompts are supported in external Chromium; an integrated Electron host that does not support them reports an explicit error. Downloads are not exposed as an agent tool. Closing/reloading the extension closes its external browser and clears its temporary session; built-in tabs remain open when control is detached. Screenshots are session-only, expire after 15 minutes, and reach the model only when it supports vision.

runPlaywrightCode uses an AST-validated, page-only interpreter in a separate process and requires approval for every new snippet. It is not a security sandbox or unrestricted Playwright. Supported host statements are const, sequential page calls with optional await, and explicit JSON-valued return. The only methods are page.evaluate(callback, optionalJsonArgument), page.title(), page.url(), page.waitForTimeout(ms), page.click(selector), and page.hover(selector). Browser JavaScript, including document and window, belongs inside the evaluation callback. Outer variables are not captured; pass JSON explicitly as the optional argument.

Example: return page.evaluate(() => document.title);

Supply exactly one of code or deferredResultId. The default wait budget is 5000 ms (positive finite values up to 30000 ms). Pending jobs return an ID; resume on the same page without rerunning code. Resolve dialogs with handleDialog. Limits: 32 KiB source, 64 KiB JSON result, eight retained jobs, one running job per page, 60 seconds execution, and five minutes completed/error retrieval. Revocation, closure, disconnect, shutdown, and cancellation invalidate jobs. Cancellation/crash/execution expiry revokes control; already-started renderer JavaScript may still continue, so cancellation is not rollback.

Run Al Hakeem: Run Browser Smoke Test for the real-browser fixture checks. Snippet and upload checks require their own approvals.

Add New RPC Methods

1. In C# Host (csharp-host/Program.cs):

case "your_method":
    result = await HandleYourMethod(request);
    break;

2. In TypeScript (src/extension.ts or panels/chatPanel.ts):

const response = await backendConnection.request('your_method', { param1: 'value' });

Add UI Features

Edit media/chat.js and media/chat.css to add new UI elements. Messages are sent to the extension via:

vscode.postMessage({
  type: 'your_event_type',
  payload: { /* data */ }
});

Troubleshooting

Blank chat panel after installing from Marketplace

Version 0.1.11 could fail during activation when VS Code exposed the proposed browser API but denied the extension permission to read it. Development launches enabled the proposal, so they did not reproduce this failure. Version 0.1.12 handles that denial and keeps chat available without browser tools.

Update the extension, then run Developer: Reload Window. If the panel is still blank, open View: Output, select Log (Extension Host), and look for Al Hakeem activation errors. Use Developer: Toggle Developer Tools to inspect webview resource or script errors. Missing .NET affects backend requests, not whether the chat UI is rendered.

Backend won't start

1. Verify the executable path in settings
2. Check that the .NET runtime is installed: dotnet --version
3. Check stderr output in VS Code debug console

Messages not sent

1. Check browser console (F12 in webview) for JS errors
2. Verify stdin/stdout connection in backend

Extension not appearing

1. Ensure npm install completed successfully
2. Run npm run build to compile TypeScript
3. Restart the extension host (Ctrl+R)

Package extension

cd .\csharp-host
dotnet publish -c Release -o lib cd .. vsce package

License

[Daarulhikmah License]

Change log:

v0.1.24:

• Fixed find_symbol tool call.
• Fixed multiple tool calls processing.

v0.1.23:

• Added missing tool calls.

v0.1.22:

• Fixed some issues run_build and get_errors where they report warnings even if ignore warning is checked.
• Fixed issue where user cannot copy text from chat area.
• Fixed issue where user bubble does not render markdown.

v0.1.21:

• Fixed some issues with run command in terminal tool call
• Improved get file tool call when getting an image file

v0.1.20:

• Added local TTS service
• Fixed some UI bug for chat history where it shows 0 token used.

v0.1.19:

• Added List skills and read skill.
• Improved TTS

v0.1.18:

• Added Settings > General > Notification Sounds: enable response/question sounds, choose from the backend sound catalog (or None), preview unsaved choices, and adjust volume. Pending questions repeat every 2-600 seconds (default 10) until answered, declined, cancelled, or the chat is changed. Playback uses the webview audio output, including with a remote backend.
• Fixed assistant text disappearing when an interactive question card renders, including restored chat history.
• TTS strips Markdown table separators, list and heading markers, strikethrough, links, and HTML formatting before pronunciation. Inline code remains speakable; fenced code and HTML comments are skipped.
• TTS buffers complete lines during streaming and flushes the final line at response completion, avoiding speech of partial Markdown links. Single-line responses start speaking when generation completes.
• Added sounds and chimes for messages and questions.
• Improved replace_string_in_file result message.

v0.1.17:

• Added TTS support.
• Fixed bubble chat grouping issue.

v0.1.16:

• Added Loading chat history.

v0.1.15:

• Restored built-in VS Code browser support as the default.
• Added an explicit built-in/external browser selector in Settings > Tools.
• Kept external Chromium as an optional mode; no automatic fallback.

v0.1.14:

• Added Marketplace-compatible browser tools using a separate visible Chromium window.
• Added first-time browser download approval and the Install Browser command.
• Removed the experimental VS Code browser API dependency.

v0.1.13:

• Omitted

v0.1.12:

• Fixed a blank chat panel on normal installations when VS Code denies the proposed browser API.
• Kept chat available when integrated browser tools are unsupported.

v0.1.11:

• Added browser features for frontend development.

v0.1.10:

• Added vLLM support.
• Fixed some issues with Auto Shrink

v0.1.9:

• Fixed an issue with file_glob_search hanging.
• Fixed an issue enable to resume chat when receive error codes from LLM server.

v0.1.8:

• Fixed an issue with drag and drop files.
• Fixed an issue with processing images with vision enabled models.

v0.1.7:

• Some fixes to replace_string_in_file
• Set default values for tool to checked.
• Fixed file_glob_search not working.
• Fixed an issue when switching pages some UI elements gets reset.
• Added media support (drag and drop)
• Fixed questions not rendering correctly.
• Reworked some of the tools calls.
• Quality of life imporvement for better User Experience.

v0.1.6:

• Fixed an issue with replace_string_in_file where it sometimes replaces a string but reports it has failed.
• Added reporting total number of lines with get_file to save on tokens.

v0.1.5

• Removed max iteration logic.
• Fixed conversation timer.
• Fixed loading chat history (some messages do not appear)
• Hide Thinking drop down selection when selected model is not a reasoning model.

v0.1.4

• Fixed an issue with git_file where it misses alot of files.

v0.1.3

• Fixed linking broken frontend contorls to the backend.

v0.1.2

• Added universal support (Linux, Mac)

v0.1.1

• Fixed backend issues with LLM connection.

v0.1.0

• First release.