Codegloss

A local-first, teaching-focused code explainer and confirm-gated agentic assistant for VS Code.

📖 Table of Contents

• Overview
• Key Features
• Core Modes
• Installation
  • From VS Code Marketplace
  • From VSIX Release
  • From Source
• Keybindings & Shortcuts
• Configuration & Settings
• Security & Local-First Philosophy
• Contributing
• License

🌟 Overview

Codegloss is a free, beginner-friendly, local-first code explanation and agentic coding extension for Visual Studio Code.

Unlike opaque AI assistants that modify code without transparency, Codegloss is built on explainability and safety:

• Teaching-First Explanations: Understand why and how code works through AST-backed structural breakdowns.
• Confirm-Gated Agent: Every file creation, code edit, and terminal command requires explicit confirmation by default.
• Local & Cloud Agnostic: Seamlessly connect to offline local models via Ollama (e.g. qwen2.5-coder, llama3, deepseek-coder) or any OpenAI-compatible BYOK (Bring Your Own Key) endpoint.

✨ Key Features

1. 🎓 Teaching-Focused Code Explanations

• Select any code in the editor to immediately get a structured, jargon-free explanation.
• Integrates native Tree-sitter WASM grammars (JavaScript, TypeScript, Python) to parse functions, classes, and scopes for contextual explanations.

2. 🛡️ Confirm-Gated Agentic Coding

• Optional tool-calling agent with granular, per-tool security policies (automatic, ask, or excluded).
• Non-destructive and safe: any file modification displays an animated, glowing confirmation card with a side-by-side diff before touching the disk.
• Privileged operations (like sudo or paths escaping the workspace root) are automatically blocked.

3. 📝 Plan Mode & Architecture Blueprints

• Create comprehensive technical implementation plans before writing any code.
• Features a single-click "Implement Plan" action that switches to Agent mode and immediately executes the blueprint.

4. 📊 Dynamic Changes Overview Bar

• Floating stats bar directly above the composer tracking all modified and created files with live line additions (+N) and deletions (-N).
• Slide-up popover with Accept All, Reject All, side-by-side Diff Viewer, and per-file Accept / Reject disk controls.
• Rejection instantly restores original file state on disk and synchronizes active editor documents.

5. 🔍 Universal @ Context Mentions

• Type @ in the chat input to search and attach context across your entire project.
• Tabbed filters for All, Files, Rule Book, and Skills Library.
• Full keyboard navigation (ArrowUp, ArrowDown, Enter, Tab, Escape) with live typing queries.

6. 📜 Workspace Rule Book & Strict Enforcement

• Define custom workspace rules and constraints (e.g. "All generated code must use TypeScript interfaces").
• Active rules in the Rule Book are strictly injected and binding on all code generation tasks.

7. 🎨 Rich Compiled Markdown & Expandable UI

• Native rendering for Markdown tables (<table>), headings, nested lists, blockquotes, and syntax-highlighted codeblocks.
• Prompts and responses over 350 characters automatically wrap into clean, collapsible containers.

8. 🔒 Zero Untitled Buffers

• Diffs are powered by a virtual codegloss-diff: document provider, preventing temporary dirty Untitled-1 / Untitled-2 scratchpad tabs from cluttering your editor.

🧭 Core Modes

Switch modes at any time using the mode dropdown or keyboard shortcuts:

🚀 Installation

1. From VS Code Marketplace

1. Open VS Code.
2. Press Ctrl+P (Windows/Linux) or Cmd+P (macOS).
3. Type:

   ext install codegloss.codegloss
   

4. Press Enter.

2. From VSIX Release

1. Download the latest codegloss-2.0.1.vsix from GitHub Releases.
2. Open VS Code, go to the Extensions view (Ctrl+Shift+X / Cmd+Shift+X).
3. Click the ... menu in the top right $\rightarrow$ Install from VSIX....
4. Select the downloaded .vsix file.

3. From Source

# Clone the repository
git clone https://github.com/manojkumarfade/CodeGloss.git
cd CodeGloss

# Install dependencies
npm install

# Build extension and grammars
npm run build

# Run unit test suite
npm test

# Package into VSIX
npm run package

⌨️ Keybindings & Shortcuts

⚙️ Configuration & Settings

All Codegloss configuration is stored locally in ~/.codegloss/config.json. Sensitive API keys are protected in VS Code's encrypted SecretStorage.

Access settings anytime via the gear icon in the chat header or with Cmd+Shift+,.

🛡️ Security & Local-First Philosophy

• Zero Cloud Leakage: When using Ollama, your code and conversation stay 100% on your local machine. No external telemetries or tracking.
• Untrusted File Boundary: Injected workspace files and URLs are fenced in untrusted delimiter blocks to prevent prompt injection vulnerabilities.
• Confirmation Gates: Shell commands and file modifications require your approval before running.
• Secret Redaction: Detected secrets, API keys, and sensitive environment variables are automatically redacted from prompts and tool outputs.

🤝 Contributing

Contributions, bug reports, and feature requests are welcome! Please check out our Contributing Guidelines and feel free to open an issue or pull request.

📄 License

This project is licensed under the MIT License.