Local Ollama connects the VS Code Chat experience to an Ollama server running on your machine. Use local models for conversation, workspace-aware code analysis, bounded file exploration, and reviewable file edits — without sending your source code to a hosted AI service.

Table of Contents

• What It Does
• Requirements
• Install
• Get Started
• Chat Usage
• Model Switching and Capabilities
• Workspace Awareness
• Editing Workflow
• Configuration
• Updating
• Diagnostics and Troubleshooting
• Development
• License

What It Does

• 🔌 Connects VS Code Chat to any reachable Ollama-compatible server
• 📋 Discovers installed Ollama models and lets you switch between them
• 💬 Streams responses through the @localllm chat participant
• 🧠 Selects relevant workspace context for questions about the current file or project
• 🔍 Explores a workspace in multiple bounded steps instead of guessing which files matter
• 🧩 Selects a model-specific tool strategy and avoids workspace tools for casual prompts
• ✏️ Proposes create, update, delete, and rename operations as structured edit plans
• 👀 Opens previews and asks for a keep/discard decision before applying each proposed file operation
• 📊 Reports progress while it connects, explores files, plans edits, and checks for updates
• ⬆️ Updates standalone VSIX installations from GitHub Releases
• 🌿 Inspects and manages the current Git repository with confirmation before mutations

Privacy note: All model requests and workspace context go to the Ollama server configured in the extension. The updater contacts GitHub only when you explicitly check for an extension update.

Requirements

Example Ollama setup:

ollama serve
ollama pull qwen2.5-coder:7b

The model name above is just an example — use any model returned by ollama list or the extension's model picker.

Install

Option A — Install the published VSIX

1. Download local-ollama-1.3.1.vsix from the GitHub release.
2. In VS Code, open Extensions.
3. Click the ... menu → Install from VSIX... → select the downloaded file.
4. Reload VS Code if prompted.

Option B — Install from source

git clone https://github.com/athulg93/vscode-localllm.git
cd vscode-localllm
npm install
npm run compile

Then use Extensions: Install from VSIX... after packaging the extension, or use Local Ollama: Update From Workspace while developing the extension.

Get Started

1. Start Ollama: ollama serve
2. Open a workspace in VS Code.
3. Run Local Ollama: Connect from the Command Palette.
4. Enter the Ollama server URL, then select a model.
5. Open VS Code Chat and address a prompt to @localllm.

The default server URL is http://localhost:11434. You can also configure the connection manually in Settings under Local Ollama.

Chat Usage

Use the participant directly in VS Code Chat:

@localllm Explain the authentication flow in this project.

Chat Commands

The updater also recognizes @localllm run update.

Git operations

For a workspace opened inside a Git repository, ask @localllm to inspect or manage Git:

@localllm Check the Git status and show the latest diff.
@localllm Stage the changed source files, commit them with "fix: improve validation", and push the current branch.

Read-only operations such as status, diff, log, and branch inspection can run automatically. Staging, committing, pushing, pulling, and switching branches always display the exact operation in a modal confirmation dialog. The Git layer does not expose arbitrary shell commands, force-push, branch creation/deletion, reset, or sensitive .env files.

Switch Models Inline

Prefix a prompt with an installed model name to use it for that request and make it the new default:

@qwen2.5-coder:7b Explain this function and suggest edge cases.

List available models with @ on its own:

@

You can also use Local Ollama: Select Model or Local Ollama: List Models from the Command Palette.

Model Switching and Capabilities

Use Local Ollama: Change Model from the Command Palette, or run:

@localllm /change-model

The extension lists the models available on the configured Ollama server, lets you choose one, and saves it as the active default for subsequent requests. During model selection and connection, the extension checks Ollama's model capabilities. If the selected model does not support tools, it displays a warning because workspace exploration and AI-assisted edit workflows may not work with that model.

Tool behavior is selected through extensible model-family profiles for Qwen, Gemma, Llama, DeepSeek, and unknown models. Profiles can use Ollama native tool calls, JSON/XML text calls, or no workspace tools. The extension also records per-model capability failures, parsing failures, unexpected tool triggers, and tool-loop incidents in VS Code global state and warns when a model repeatedly misbehaves.

Workspace Awareness

For questions that need repository context, the extension performs several host-owned operations:

The model can chain these tools — for example: discover likely files → search for a symbol → read the relevant implementation. Tool calls have a configurable per-request budget so a large request can explore more than eight times without becoming an unbounded loop.

Excluded by default: node_modules, .git, dist, out, build, .next, .turbo, .cache.

File paths must stay workspace-relative and cannot contain parent-directory traversal.

Editing Workflow

Ask for a focused change:

@localllm /edit Add input validation to the current API handler.

The extension then:

1. Explores relevant files with bounded tools.
2. Requests a structured edit plan from Ollama.
3. Validates the proposed paths and operations on the host.
4. Previews diffs for up to three files.
5. Lets you decide — keep or discard each validated operation.
6. Applies selected changes with VS Code WorkspaceEdit and saves the affected documents.

Supported operations: create, update, delete, rename. The extension protects sensitive or generated locations, rejects unsafe paths, limits the number and size of edits, and skips operations that fail validation. A proposed edit is never applied without your confirmation.

Equivalent workflows are also available from the Command Palette:

• Local Ollama: Apply Suggested Edit — edits the current file based on a prompt.
• Local Ollama: Refactor Project — proposes a project-level refactor.

Configuration

All settings live under Settings → Extensions → Local Ollama.

The tool-call limit is a guardrail, not a target. Requests stop as soon as the model has enough context; requests that reach the configured maximum receive a bounded-limit error instead of continuing forever.

Updating

Installed VSIX or release update

Run Local Ollama: Check for Updates from the Command Palette, or:

@localllm /update

The updater:

1. Checks the latest release at GitHub Releases.
2. Compares the release version with the installed extension version.
3. Finds the release .vsix asset and asks for confirmation.
4. Downloads and validates the VSIX archive in VS Code extension storage.
5. Installs the update and offers to reload the window.

If no newer release is available, the extension reports that it's already up to date. Marketplace installations, when available, can use VS Code's normal extension update service.

Update from the source workspace

Local Ollama: Update From Workspace is intended for contributors developing this extension from source. It validates that the open workspace's package.json matches this extension, asks for confirmation before running any commands, compiles the workspace, packages the VSIX, installs it into the current VS Code instance, and offers to reload the window. Dependencies must already be installed.

Diagnostics and Troubleshooting

Open Local Ollama: Open Activity Log or the Local Ollama output channel for connection failures, model resolution, context selection, tool progress, skipped edits, update errors, and cancellation messages.

Development

Install dependencies and compile:

npm install
npm run compile

Lint and run the unit test suite (covers the pure logic in src/core/):

npm run lint
npm test

Build a VSIX:

npm run package -- --allow-star-activation --skip-license --allow-missing-repository

The output file is named local-ollama-<version>.vsix.

Automated tests currently cover src/core/ only (prompt-intent classification, edit-plan parsing, path safety, and NDJSON stream parsing). Before publishing, also validate: compilation, VSIX integrity, a local Ollama request, and the GitHub release asset.

License

This project is licensed under the MIT License.