deeplocal-chat-adapter

deeplocal-chat-adapter is a VS Code extension that connects local DeepLocal models and remote OpenAI-compatible APIs to VS Code chat. It provides a sidebar for conversational coding tasks and registers discovered models in the VS Code chat model picker.

Install from GitHub Releases

Download the latest .vsix package from the GitHub Releases page. You do not need Node.js or npm to install a prebuilt VSIX.

1. Download the deeplocal-chat-adapter-<version>.vsix file from the release's Assets section.
2. Open VS Code (version 1.104 or later) and go to the Extensions view (Ctrl+Shift+X on Windows/Linux or Cmd+Shift+X on macOS).
3. Select the ... menu in the Extensions view and choose Install from VSIX....
4. Select the downloaded file and reload VS Code if prompted.
5. Open the Command Palette and run deeplocal-chat-adapter: Open.
6. Configure a running local DeepLocal service or a compatible remote API as described in Configure a backend.

Alternatively, install the downloaded package from a terminal:

code --install-extension ./deeplocal-chat-adapter-0.1.0.vsix

Replace the example filename with the VSIX version you downloaded. The code command must be available on your PATH. To replace an already installed copy, you can add --force.

VSIX installations from GitHub Releases generally require manually downloading and installing newer versions. The VSIX contains the extension, not the DeepLocal model service.

Build and publish a VSIX

For maintainers, this repository already provides a VSIX packaging script:

npm ci
npm run check
npm run package:vsix

The last command runs the production prepublish build and produces deeplocal-chat-adapter-<version>.vsix in the repository root. Confirm the extension works in VS Code before publishing.

To publish a release manually:

1. Ensure the intended source changes are committed and pushed to GitHub.
2. Open the Releases page and choose Draft a new release.
3. Choose an existing version tag or create a new one such as v0.1.0 (without spaces), targeting the commit used to build the VSIX.
4. Enter a release title and release notes.
5. Upload the generated .vsix file under Assets.
6. Review the tag, notes, and attached file, then choose Publish release.

Keep the tag, extension version in package.json, and packaged VSIX version consistent. GitHub Releases publishing is currently a manual process; the package:vsix script only builds the package and does not upload it.

Quick Start & Testing (Debug Mode)

To quickly test the extension during development:

1. Open the project in VS Code.
2. Press F5, or open Run and Debug and select Start Debugging.
3. A new Extension Development Host window opens.
4. In that window, open the VS Code Chat view or the built-in sidebar chat to test the deeplocal-chat-adapter integration.

Features

• Use discovered local DeepLocal models or a remote OpenAI-compatible API.
• Chat in the dedicated DeepLocal sidebar, which can be moved to VS Code's Secondary Side Bar.
• Run coding tasks with workspace-aware tools for reading, searching, editing, creating, opening, and trashing individual files, as well as running commands.
• Review file changes before approval, with a diff preview where available.
• Review staged, unstaged, or committed Git changes in a dedicated read-only mode.
• Choose an approval mode: approve every operation, automatically allow safe operations, allow all operations, or use discussion-only mode.
• View streamed progress updates, tool activity, and final answers separately.
• Copy completed assistant answers, including folded code, using the copy icon below each reply. A checkmark and “Copied” confirm success briefly.
• Use the Responses API with compatible endpoints to display provider reasoning summaries separately from the answer.
• Keep recent chat sessions per workspace across webview recreation and reloads.

Requirements

• VS Code 1.104 or later.
• Node.js and npm to build, test, or package the extension.
• For the default local backend, a running DeepLocal service exposing an OpenAI-compatible API. Its default URL is http://127.0.0.1:14567/v1.

The remote backend is optional. It works with an OpenAI-compatible service and may incur charges from that provider.

Quick Start

1. Clone this repository and open it locally:

   git clone https://github.com/petertzy/deeplocal-chat-adapter.git
   cd deeplocal-chat-adapter
   

2. For the final packaged-extension install, run:

   npm run install:local
   

   This installs dependencies, builds a VSIX package, and installs it into your normal VS Code installation. The script requires the code command to be available in your shell. For development, use the debug workflow above or the guidance in CONTRIBUTING.md.

   You can also run the script directly:

   ./scripts/install-local.sh
   

3. Open VS Code's Command Palette:

   • macOS: Command+Shift+P
   • Windows/Linux: Ctrl+Shift+P

4. Run:

   Developer: Reload Window
   

5. Open the Command Palette again and run:

   deeplocal-chat-adapter: Open
   

6. Select a DeepLocal model in the VS Code chat model picker.

Use the sidebar

Open a project folder, run deeplocal-chat-adapter: Open, choose a model, and enter a task. The selected approval mode determines whether the sidebar operates as an agent or as a discussion-only chat.

Agent mode requires an open workspace folder and a model that advertises tool calling support. The available tools can inspect the workspace, read files and diagnostics, search, edit or create files, open files, run commands, and move a single explicitly requested file to the system trash. Paths are restricted to the workspace. create_file does not overwrite an existing file.

In a multi-root window, use the Workspace button above the conversation to choose the folder for agent operations. The picker shows each folder's URI to distinguish duplicate names. A single open folder is selected automatically; with several folders, choose one before sending an agent task. Cancelling the picker keeps the previous choice. The choice lasts until the extension reloads.

The selected folder stays visible and cannot be changed while a task runs. Removing that folder stops the task; already applied changes are retained. File discovery, summaries, diagnostics, editor context, relative tool paths and command working directories use the selected folder. Absolute paths and URI inputs are rejected by file tools. Conversation history is retained when you change folders. Existing symlink following and command permissions are unchanged; the folder selection is not an operating-system sandbox.

Tool activity labels show only the action and a short target. Recognized sensitive filenames (such as .env, credential files and private keys), authorization text, credential assignments/options and URL credentials are replaced with [sensitive target redacted] before the label is shortened. Ordinary paths and search terms remain visible. Recognizable sensitive labels in saved activity are also redacted when displayed again. These are limited presentation rules, not a complete secret scanner; approval prompts, tool results and model conversation history retain their existing behavior.

read_file reads UTF-8 text. Files containing NUL bytes or invalid UTF-8 return an error identifying the workspace-relative path instead of their contents.

Use Stop to cancel the active request or pending approval. Changes already applied before cancellation remain in place.

The sidebar stores up to 20 recent sessions for each workspace in VS Code workspaceState. Each stored session retains recent conversation history and its rendered transcript. Empty VS Code windows share one session scope because they do not have a durable workspace identity.

Task history shows each session title followed by a short preview of its latest user request. Long previews are shortened without splitting Unicode characters; the full preview is available in the selector's tooltip and each option's accessible label. Empty sessions keep their title alone.

Sidebar placement

The Open command reveals the sidebar at its saved VS Code location. To put it on the right, right-click the DeepLocal view title and select Move View → Secondary Side Bar. If necessary, first run View: Toggle Secondary Side Bar Visibility from the Command Palette.

Review code changes

Choose Review in the sidebar, select a model with tool calling, and choose Unstaged, Staged, or Commit range. A written prompt is optional; use it to focus the review on a particular concern. For a commit range, enter base and target refs (hashes, branches, or tags). The defaults are HEAD~1 and HEAD; the review compares those two commits directly, without computing a merge base.

Review mode inspects changes, surrounding source, and relevant tests. It cannot edit files, run commands, or execute tests, even when Full access is selected. It uses its own review context rather than replaying normal agent instructions. Switching back to Build / Ask requires confirmation; fixes must be requested as a new normal-mode task and follow the selected approval setting. Starting or switching tasks keeps Review active until you explicitly leave it.

Reports separate confirmed findings from potential risks and include severity (Critical, High, Medium, or Low), explanation, and verbatim source evidence. Source buttons open a read-only copy of the reviewed content, including deleted or historical lines. The copy icon below the report copies it as Markdown for you to paste into a pull request; it does not connect to or post on GitHub. Completed reports are retained in the existing workspace session history.

Git must be available, and the selected local workspace folder must be inside a complete Git repository. Partial/promisor clones are rejected because reading missing objects can trigger a fetch. Repository-configured executable Git helpers are disabled during review; any disabled content filters are reported as a limitation. Reviews cover tracked, saved files only: untracked files and unsaved editor buffers are excluded. Staged reviews inspect index content; commit reviews inspect the selected revisions. An unstaged review is rejected if its underlying changes or inspected saved files change before completion. Binary and submodule contents are reported as limitations. Diffs and individual source files are limited to 60,000 characters; oversized diffs require a narrower comparison. Search is bounded and reports skipped or truncated evidence.

Empty diffs do not make a model request. Empty findings do not guarantee that the changes are correct. Every report states that tests were not run.

Configure a backend

The extension uses the local DeepLocal backend by default. Open the sidebar settings and choose Change under Provider, or open deeplocal-chat-adapter: Open Settings and set deeplocal.backend.

For a remote backend:

1. Set deeplocal.backend to remote.
2. Set deeplocal.remote.baseUrl and deeplocal.remote.model as needed.
3. Use Set API key in the sidebar or run deeplocal-chat-adapter: Set Remote API Key. The remote key is stored in VS Code SecretStorage, not in workspace settings.
4. Run deeplocal-chat-adapter: Check Connection to verify model discovery. Use deeplocal-chat-adapter: Test Remote API Request to test a minimal streamed request to the selected remote model.

Model discovery uses <base URL>/models. A remote backend falls back to the configured deeplocal.remote.model when discovery is unavailable, but that fallback does not make a connection check succeed. Local model discovery must return models successfully.

Base URLs must use HTTP(S) and must not include embedded credentials, a query, or a fragment. The connection check reports configuration, network, timeout, HTTP, JSON, schema, or empty-model failures without exposing authorization headers or response bodies.

Protocols, model metadata, and reasoning summaries

Chat Completions is the default protocol. Select Responses only when the selected backend and model support the Responses API. In Responses mode, the extension can request reasoning.summary: "auto" and renders any provider summary as a separate sidebar entry. Providers may return no summary. Disable deeplocal.reasoningSummary for models that reject summaries.

Responses requests use store: false. To continue an agent task, the extension keeps opaque Responses output items only in that workspace's chat history and sends them back only to the same backend URL and model. Raw reasoning content is neither displayed nor logged.

The extension reads optional /models metadata for input/output token limits, tool-calling capability, protocol, and endpoint. Valid metadata overrides the fallback settings above. Models without tool support remain available for discussion-only chat. The adapter sends text input only; image input is not supported.

Commands

• deeplocal-chat-adapter: Open — Reveal the sidebar.
• deeplocal-chat-adapter: New Session — Start a sidebar session.
• deeplocal-chat-adapter: Refresh Models — Refresh the active backend's discovered models.
• deeplocal-chat-adapter: Check Connection — Validate the active backend's models endpoint.
• deeplocal-chat-adapter: Test Remote API Request — Test remote streamed chat generation without tools.
• deeplocal-chat-adapter: Open Settings — Open this extension's settings.
• deeplocal-chat-adapter: Set Remote API Key / Clear Remote API Key — Manage the remote credential in SecretStorage.

Development and tests

npm run check

This runs TypeScript checking, linting, and unit tests. Additional commands:

• npm run watch — Watch the bundle and type checks.
• npm run test:watch — Watch unit tests.
• npm run test:webview — Run browser tests for the sidebar. Run npx playwright install chromium once if Chromium is not installed.
• npm run test:integration — Compile and launch an isolated VS Code Extension Host against a local fake OpenAI-compatible server.
• npm run package — Build the production bundle.
• npm run package:vsix — Create a distributable VSIX.

Unit, webview, and integration tests do not require a live DeepLocal service or a billable remote API key.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, validation, and pull request guidance.

License

MIT. See LICENSE.