VS Code Extension

Context Engine Uploader extension for automatic workspace sync and Prompt+ integration.

Documentation: README · Getting Started · Configuration · IDE Clients · MCP API · ctx CLI · Memory Guide · Architecture · Multi-Repo · Observability · Kubernetes · VS Code Extension · Troubleshooting · Development

On this page:

• Quick Start
• Features
• Workflow Examples
• Installation
• Configuration
• Commands

Quick Start

1. Install: Build the .vsix and install in VS Code (see Installation)
2. Configure server: Settings → contextEngineUploader.endpoint → http://localhost:8004 for the dev-remote Docker stack (or your upload_service URL)
3. Index workspace: Click status bar button or run Context Engine Uploader: Start
4. Use Prompt+: Select code, click Prompt+ in status bar to enhance with AI

Features

• Auto-sync: Force sync on startup + watch mode keeps workspace indexed
• Prompt+ button: Status bar button to enhance selected text with unicorn mode
• Output channel: Real-time logs for force-sync and watch operations
• GPU decoder support: Configure llama.cpp, Ollama, or GLM as decoder backend
• Remote server support: Index to any Context-Engine server (local, remote, Kubernetes)
• MCP + ctx scaffolding: Auto-writes Claude Code/Windsurf MCP configs, optional Claude prompt hook, and ctx_config.json wired to collection and decoder settings

Workflow Examples

Local Development (dev-remote stack)

Context-Engine running via docker-compose.yml on same machine:

Endpoint: http://localhost:8004
Target Path: (leave empty - uses current workspace or auto-detect)

Open any project → extension auto-syncs → MCP tools have code context.

Remote Server

Context-Engine on team server:

Endpoint: http://context.yourcompany.com:9090
Target Path: /Users/you/projects/my-app

Local code indexed to shared server. Team members search across indexed repos.

Multi-Project Workflow

Index multiple projects to same server:

1. Open Project A → auto-syncs to codebase collection
2. Open Project B → auto-syncs to same collection
3. MCP tools search across both projects

Prompt+ Enhancement

1. Select code or write a prompt in your editor
2. Click Prompt+ in status bar (or run command)
3. Extension runs ctx.py --unicorn with your selection
4. Enhanced prompt replaces selection with code-grounded context

Example input:

Add error handling to the upload function

Example output:

Looking at upload_service.py lines 120-180, the upload_file() function currently lacks error handling. Add try/except blocks to handle:
1. Network timeouts (requests.exceptions.Timeout)
2. Invalid file paths (FileNotFoundError)
3. Server errors (HTTP 5xx responses)

Reference the existing error patterns in remote_upload_client.py lines 45-67 which use structured logging via logger.error().

Claude Code hook (optional)

For Claude Code, you can also enable a /ctx hook so that each prompt is expanded via ctx.py before it reaches Claude:

• The extension can auto-write MCP config and, on Linux/dev-remote, a Claude hook when claudeHookEnabled is turned on.
• See docs/ctx/claude-hook-example.json for a minimal UserPromptSubmit hook that shells out to ctx-hook-simple.sh.

Installation

Build Prerequisites

• Node.js 18+ and npm
• Python 3 available on PATH for runtime testing
• VS Code Extension Manager vsce (npm install -g @vscode/vsce) or run via npx

Install Dependencies

cd vscode-extension/context-engine-uploader
npm install

Package the Extension

cd vscode-extension/context-engine-uploader
npx vsce package

This emits a .vsix file such as context-engine-uploader-0.1.0.vsix.

Test Locally

1. In VS Code, open the command palette and select Developer: Install Extension from Location....
2. Pick the generated .vsix.
3. Reload the window when prompted.

Key Settings After Install

• Context Engine Upload output channel shows force-sync and watch logs.
• Context Engine Uploader: Index Codebase command or status bar button runs a force sync followed by watch.
• Configure contextEngineUploader.targetPath, endpoint, and (optionally) MCP settings (mcpIndexerUrl, mcpMemoryUrl, mcpTransportMode, mcpClaudeEnabled, mcpWindsurfEnabled, autoWriteMcpConfigOnStartup) under Settings → Extensions → Context Engine Uploader.

Prerequisites

Python 3.8+ must be available on the host so the bundled client can run.

Configuration

All settings live under Context Engine Uploader in the VS Code settings UI or settings.json.

Commands and lifecycle

• Context Engine Uploader: Start — executes the initial --force followed by --watch using the configured settings.
• Context Engine Uploader: Stop — terminates any running upload client processes.
• Context Engine Uploader: Restart — stops current processes and re-runs the startup sequence.
• Context Engine Uploader: Show Upload Service Logs — opens a terminal and tails docker compose logs -f upload_service.
• Context Engine Uploader: Prompt+ (Unicorn Mode) — runs scripts/ctx.py --unicorn on your current selection and replaces it with the enhanced prompt (status bar button).

The extension logs all subprocess output to the Context Engine Upload output channel so you can confirm uploads without leaving VS Code. The watch process shuts down automatically when VS Code exits or when you run the Stop command.

Troubleshooting

Extension not syncing

1. Check Context Engine Upload output channel for errors
2. Verify endpoint setting points to running upload service
3. Ensure Python 3.8+ is available at configured pythonPath

Prompt+ not working

1. Verify decoder is running: curl http://localhost:8081/health
2. Check decoderUrl setting matches your decoder (llama.cpp, Ollama, or GLM)
3. For GPU decoder: enable useGpuDecoder setting

Connection refused

# Verify upload service is running
curl http://localhost:8004/health

# Check Docker logs
docker compose logs upload_service

Remote server issues

1. Ensure port 9090 is accessible from your machine
2. Check firewall rules allow inbound connections
3. Verify server's upload_service container is running