Heap Code
Model-agnostic AI coding assistant for VS Code and the terminal. Chat, ghost-text completions, inline edits, an autonomous agent, AI PR review, and semantic codebase search — with any OpenAI-compatible API, local or cloud.
Three surfaces over one shared engine:
Heap Chat ships in the same CLI: heapcode chat [folder] is a knowledge assistant over a folder of your own files (PDFs, Word documents, spreadsheets, photos). It answers from them, says which file each answer stood on, and never writes over them. heapcode web also mounts it at /chat.
There is also heapbrowse — a separate product on the same engine: a Chrome side-panel agent that reads the page you are on and can operate it for you. browse.heaplabs.dev
Privacy first
Your code never leaves your machine except to the model endpoint you configure — no proprietary backend, no account. Point it at Ollama on your LAN and your code stays home.
Heap Code does send anonymous usage telemetry by default (which features get used, coarse error counts — never code, prompts, or file contents/paths). Turn it off via heapcode.telemetry.enabled or VS Code's own telemetry.telemetryLevel. See packages/vscode/README.md for details. heapbrowse does the same for the extension's own usage — never the pages you visit — with a switch in its Settings panel.
Works with
| Local | Cloud |
|---|
| Ollama, LM Studio, vLLM, LocalAI | Ollama Cloud, OpenAI, Azure OpenAI, OpenRouter, Groq, Together AI, NVIDIA NIM |
…plus any custom OpenAI-spec endpoint. A provider is a named connection (an endpoint + its key); one global role table — chat / edit / apply / completion / agent / embeddings / rerank / context — says which model on which connection serves each role. Every role can point at a different connection: embeddings on a local Ollama box while chat and agent run on a cloud model. Set it on the settings screen, or with heapcode model in the CLI.
Features
- Chat — streaming markdown with syntax highlighting; history per workspace; slash commands (
/explain, /fix, /review, /security-review, …) with autocomplete; custom prompts; @selection @file @problems @workspace context mentions; code-block Copy / Insert / Apply actions
- Completions — ghost text with proper FIM formats per model family (Qwen, DeepSeek, StarCoder, CodeLlama, Codestral, CodeGemma), native server-side FIM on Ollama, debounced + cancellable, latency stats in the output panel; repo-level context from the semantic-search index (keyword-only while typing, full semantic search on manual trigger) alongside open-editor snippets
- Inline edit — select code,
Ctrl+I/Cmd+I, describe the change, review a native diff, accept from the diff title bar
- Agent mode — reads, searches, edits files and runs commands to complete tasks autonomously; every non-read action goes through permission prompts (Allow Once / Session / Always, Safe Mode); one-click Revert all restores every touched file byte-identical; a persisted, incrementally-updated repo map (file paths + top-level symbol names, no model required) gives it a cheap way to orient before searching
- Semantic search (RAG) — background incremental index using your embeddings model; AST-aware chunking (TS/TSX/JS/JSX/Python, line-window fallback elsewhere); hybrid search (embeddings + BM25 keyword, fused) on by default; optional contextual retrieval (LLM blurb per chunk) via the Context model role; powers
@workspace and the agent's semantic_search; degrades gracefully to text search with no embedder
- MCP — register Model Context Protocol servers (stdio / HTTP / SSE); their tools appear in agent mode under the same permission system
- VS Code tool interop — any tool another installed extension registered via VS Code's Language Model Tools API (Python, Jupyter, SonarQube, …) shows up in agent mode too, same tools picker, same permission system
- Project memory —
.heapcode/HEAPCODE.md + .heapcode/memory.md are loaded into every chat and agent session (falls back to AGENTS.md if neither exists — reads the same instructions you've already written for other AI tools); add path-scoped rules with .heapcode/instructions/*.md files (optional front-matter applyTo: "**/*.tsx" glob — applies everywhere if omitted); the agent can propose short "worth remembering" notes at the end of a session, added to memory only with your confirmation ()
Quick start
CLI: npm install -g @heaplabs/heapcode-cli, then run heapcode — it walks you through picking a provider and model on first run. heapcode -p "task" runs the same agent headlessly.
VS Code:
pnpm install && pnpm build, then press F5 in VS Code (or install the packaged .vsix).- Click the ✨ status bar item → Add profile → pick your provider (e.g. Ollama) → pick a model.
- Recommended local models: chat
llama3.1:8b+ · completion qwen2.5-coder:1.5b · embeddings nomic-embed-text.
- Open the Heap Code icon in the activity bar and start chatting; select code and hit
Cmd+I to edit.
API keys are stored in the OS keychain via VS Code SecretStorage — never in settings files. The CLI has no keychain dependency (so headless and CI machines work): it uses a chmod 600 file under ~/.heapcode.
Browser UI
cd your-project
heapcode web # http://127.0.0.1:7411, opens with a one-time token
heapcode web --port 8080
heapcode web --host 0.0.0.0 # reachable from your phone/tablet — read the warning it prints
Same engine as the CLI and the extension, in a browser tab: streaming chat with
collapsible tool chips, inline permission cards, a conversation sidebar, and a
workspace panel with Changes (per-file diffs, per-file and session-wide
revert, a checkpoint timeline to rewind to), Files, Index (semantic
index + repo map status, with a rebuild), Terminal (what the agent ran and
what it printed), and Preview (artifacts the agent renders — HTML in a
sandboxed frame, Mermaid, Markdown, SVG, code).
Things the terminal can't do: paste or drag a screenshot straight into the
composer, and get a desktop notification when a long run finishes in a
background tab.
Keyboard: ⌘/Ctrl+K command palette · ? shortcut list · ⌘/Ctrl+B
workspace panel · ⌘/Ctrl+, settings · ⌘/Ctrl+Shift+N new chat · / focus
the composer · Esc stop the run.
Security. The web host runs shell commands as you, by design — treat it as
the terminal you launched it from:
- Binds
127.0.0.1 unless you pass --host, which prints a warning and shows a
banner in the page.
- A fresh 32-byte token per launch, delivered once in the URL and immediately
exchanged for an
HttpOnly cookie, so it stops living in the address bar.
- Origin allowlist on the WebSocket upgrade (CSRF defense), constant-time token
comparison, and every workspace read root-jailed to the folder you opened.
- Ten failed tokens from one address and that address is refused for fifteen
minutes.
- API keys never reach the browser. Settings sends keys up and the host
returns only whether one exists.
Closing the tab does not stop a run — the host owns run state, so reopening
reattaches to whatever is still going.
Desktop app
The same UI in a native window — no browser tab, no terminal to keep open:
pnpm build && pnpm desktop # dev: runs packages/cli/dist under Electron
pnpm --filter @heapcode/desktop dist # installers → packages/desktop/release
It asks for a project folder on first launch (then remembers it; File → Open Folder… switches), starts the web host on a free loopback port as a child process, and stops it when you quit. pnpm desktop /path/to/project opens a specific folder.
Repository layout
packages/core IDE-agnostic engine: providers, agent loop, tools, RAG, prompts
packages/host Shared host runtime: config, secrets, tools, checkpoints, permissions
packages/vscode VS Code extension (thin adapter over core)
packages/cli Terminal CLI over core — published as @heaplabs/heapcode-cli
packages/web-host Local server behind `heapcode web`: WS protocol, sessions, artifacts
packages/web-ui React SPA the web host serves
packages/desktop Electron shell: `heapcode web` in a native window
packages/webview-ui React chat UI
docs/PRD.md Product requirements (source of truth)
docs/PLAN.md VS Code extension milestone tracker + decisions log
docs/CLI_PLAN.md CLI milestone tracker + decisions log
docs/CHAT_MODE_PLAN.md Heap Chat mode — decisions, guardrails, milestone tracker
core never imports vscode (lint-enforced) — the CLI and any future JetBrains/Neovim adapters reuse it wholesale.
Development
pnpm install
pnpm build # webview + extension
pnpm test # core unit tests (offline mock provider)
pnpm typecheck && pnpm lint
cd packages/vscode && pnpm package # build the .vsix
License
PolyForm Noncommercial License 1.0.0 —
free to use, modify, and share for any noncommercial purpose (personal use, private/internal
use, research, nonprofits, education, government). Commercial use — selling it, hosting it as
a paid service, bundling it into a commercial product — isn't permitted under this license.
Versions 0.1.x were released under Apache-2.0 and remain available under those original
terms; this license applies from 0.2.0 onward.
