AI Code Commenter

A VS Code extension that generates meaningful, professional code comments using Gemini or a local Ollama model — explaining why code exists (purpose, algorithm choice, edge cases, complexity), not restating what each line obviously does. No backend: the extension talks to the provider's API directly from the extension host.

Features

• Generate AI Comments — select code, right-click (or Ctrl+Alt+C / Cmd+Alt+C), and get language-appropriate comments inserted in place.
• Two interchangeable AI backends — Google's Gemini API (cloud, needs an API key), or a locally-running Ollama model (free, no API key, runs entirely on your machine). Switch between them with the aiCodeCommenter.provider setting; adding a third provider (OpenAI, Claude, …) means implementing one interface, nothing else changes.
• Detects existing comments so it doesn't duplicate good ones or clutter already-well-documented code; can optionally improve vague ones.
• Supports C++, Java, Python, JavaScript, and TypeScript, each with its correct doc-comment style (Javadoc/JSDoc, Python docstrings, etc.).
• Runs Prettier on generated output where supported (JS/TS).
• Verifies the AI's output before applying it: if the model alters or drops so much as one line of your original code instead of only adding comments, the edit is refused rather than applied — your code is never silently changed.

Requirements

• VS Code ^1.85.0
• Node.js and npm (for building from source)
• Either a Gemini API key, or Ollama installed locally with a model pulled (e.g. ollama pull llama3.1)

Getting started (running from source)

npm install
npm run compile

Then in VS Code: press F5 (or Run → Start Debugging). This builds the extension and opens a second Extension Development Host window with it loaded — that's how you try the extension during development; there's nothing else to "run" directly.

In that new window, pick one:

Using Gemini (default):

1. Ctrl+Shift+P → "AI Code Commenter: Set Gemini API Key" → paste your key. It's stored via VS Code's encrypted SecretStorage, never written to disk in this repo or your workspace.

Using Ollama (free, local):

1. Install Ollama and run ollama pull llama3.1 (or any other model you prefer).
2. Make sure Ollama is running (ollama serve, or just open the Ollama app).
3. In Settings (Ctrl+, → search "AI Code Commenter"), set aiCodeCommenter.provider to ollama. Optionally set aiCodeCommenter.model to match whatever model you pulled (defaults to llama3.1).

Then, either way: open a file in a supported language, select some code, right-click → "Generate AI Comments".

Commands

Command	Description
AI Code Commenter: Generate AI Comments	Comment the current selection
AI Code Commenter: Set Gemini API Key	Store your API key securely
AI Code Commenter: Clear Gemini API Key	Remove the stored key

Settings

Setting	Default	Description
aiCodeCommenter.provider	gemini	gemini | ollama (see Architecture — adding another provider means one new class)
aiCodeCommenter.model	(provider-dependent)	Model name sent to the provider. Defaults to gemini-3.5-flash for Gemini or llama3.1 for Ollama if left unset. For Gemini, check the current model list if it 404s as retired; for Ollama, the model must already be pulled (ollama pull <name>)
aiCodeCommenter.ollamaBaseUrl	http://localhost:11434	Base URL of the local Ollama server, only used when provider is ollama
aiCodeCommenter.verbosity	standard	minimal | standard | detailed
aiCodeCommenter.autoFormat	true	Run Prettier on generated output where supported
aiCodeCommenter.improveExistingComments	true	Allow rewriting vague/outdated comments, not just adding new ones

Development

npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm run format       # prettier --write
npm run compile      # bundle to dist/extension.js
npm test             # launches a real VS Code instance and runs test/suite/*.test.js
npm run vsce:package # produce a .vsix

Architecture

src/
  commands/     command registration + orchestration (generateComments, manageApiKey)
  services/     promptBuilder, ai/ (AIProvider interface + GeminiProvider +
                OllamaProvider + factory)
  parsers/      languageDetector, commentDetector
  formatters/   Prettier integration
  config/       settings (typed config access), secretStore (SecretStorage)
  types/        shared types
  utils/        errors (typed hierarchy + user-facing messages), logger,
                codePreservation (verifies the AI only inserted lines), retry

Adding a new AI provider (OpenAI, Claude, …) means implementing the AIProvider interface in services/ai/ and registering it in providerFactory.ts — nothing else changes. GeminiProvider (cloud, needs an API key, uses @google/generative-ai) and OllamaProvider (local, no key, plain fetch against Ollama's REST API) are the two current examples.