CodeBuddy

Autonomous AI Software Engineer for Visual Studio Code

CodeBuddy is a multi-agent AI software engineer that operates inside VS Code. It plans, writes, debugs, tests, documents, and deploys entire features autonomously -- reading your codebase, running terminal commands, editing files, searching the web, and correcting its own mistakes until the task is done.

It supports several AI providers (cloud and local), diverse built-in tools, pre-configured external connectors, and a Model Context Protocol gateway for unlimited extensibility. It ships with scheduled automations, a built-in tech news reader, persistent agent memory, and full internationalization in 7 languages.

Table of Contents

• Architecture
• Agent System
• Operating Modes
• AI Providers
• Built-in Tools
• Commands
• Inline Code Completion
• Diff Review System
• Model Context Protocol (MCP)
• Connectors and Integrations
• Context Pipeline
• Project Rules and Skills
• Persistent Memory
• Coworker Automations
• Smart Reader
• Observability
• Internationalization
• Settings
• Installation
• Configuration
• Data Storage
• Troubleshooting
• Contributing
• License

Architecture

CodeBuddy is built on an event-driven, layered architecture designed for extensibility, provider-agnosticism, and real-time streaming.

Orchestrator

The Orchestrator is a singleton event bus at the center of the system. Every subsystem communicates exclusively through publish/subscribe events. The Orchestrator never calls services directly -- it emits typed events and listeners react independently. This fully decouples the agent layer, webview layer, and service layer from one another.

Agent Execution Pipeline

User message (webview)
  --> BaseWebViewProvider receives via onDidReceiveMessage
    --> InputValidator sanitizes input
    --> MessageHandler routes to CodeBuddyAgentService
      --> DeveloperAgent invokes createDeepAgent()
        --> LangGraph graph executes (reason -> act -> observe loop)
          --> Tools execute (file edit, terminal, search, MCP, etc.)
          --> Stream events emitted per token / per tool call
        --> Events flow back through Orchestrator
      --> WebViewProvider forwards to webview via postMessage
User sees streamed response with real-time tool activity indicators

Webview Communication

The extension host and the React webview communicate over a bidirectional postMessage protocol. The webview sends structured commands The extension responds with typed events.

Persistence Strategy

Agent System

Multi-Agent Architecture

CodeBuddy uses a multi-agent architecture built on the LangGraph DeepAgents framework. A Developer Agent coordinates the work, with seven specialized subagents that each receive role-specific filtered tools:

Self-Healing Execution

When the agent encounters a failure -- a build error, a failed test, an invalid command output -- it does not stop. It reads the error, analyzes the root cause, applies a correction, and retries. This loop continues until the task succeeds or the agent determines the issue requires human intervention.

Human-in-the-Loop

Destructive operations (such as file deletion) trigger an interrupt that pauses execution and asks for explicit approval. The user can approve, edit, or reject the proposed action before the agent continues.

Operating Modes

Agent Mode -- Full autonomous execution. The agent has access to all tools: file creation and editing, terminal commands, web search, codebase analysis, MCP integrations, and debugger access. File changes go through the diff review system for approval.

Ask Mode -- Direct question-and-answer interaction. The agent answers questions, explains code, and provides suggestions without modifying files or running commands. Context is gathered from your workspace automatically.

AI Providers

CodeBuddy supports 10 AI providers. Switch between them at any time without restarting.

Inline code completion can use a separate provider and model from the chat, allowing you to run a fast local model for completions while using a cloud model for agent tasks.

Built-in Tools

The agent has access to over 20 tools that it selects and invokes autonomously:

Commands

All commands are available from the Command Palette, the right-click context menu, or their keyboard shortcuts.

Documentation Generator

The documentation command supports five output types (Complete Suite, README Only, API Docs, Architecture Docs, Component Docs), three output formats (Markdown, HTML, Both), and three diagram formats (Mermaid, PlantUML, ASCII).

Inline Code Completion

CodeBuddy provides a Fill-in-the-Middle (FIM) inline completion engine that operates independently from the chat:

• Ghost text suggestions appear as you type, using context from imports, surrounding code, and file structure.
• Can use a different AI provider and model from the main chat -- run a fast local model for completions while using a cloud model for agent tasks.
• Configurable debounce delay (default 300ms), max tokens, and trigger mode (automatic or manual).
• LRU caching (50 entries) prevents redundant API calls for repeated completions.
• Multi-line completion support.

Diff Review System

Every file change the agent proposes goes through a review pipeline:

• Changes appear in the Pending Changes panel in the sidebar with a visual diff.
• Open any change in VS Code's native side-by-side diff editor.
• Apply or reject individual changes with toolbar buttons.
• Recent changes history tracks the last 50 modifications.
• Auto-apply mode is available for workflows that do not require manual approval.
• Real-time event notifications keep the UI synchronized.

Model Context Protocol (MCP)

CodeBuddy has first-class support for the Model Context Protocol, the open standard for connecting AI agents to external tools and data sources.

• Docker Gateway Mode -- Run a single unified MCP catalog via docker mcp gateway run, exposing all configured tool servers through one endpoint.
• Multi-Server Mode -- Connect to multiple independent MCP servers simultaneously, each with its own transport (SSE or stdio).
• Presets -- Built-in preset for Playwright browser automation. Add custom presets for your own tool servers.
• Tool Management -- Enable or disable individual tools per server from the Settings panel.
• Auto Shutdown -- The Docker gateway shuts down automatically after 5 minutes of inactivity to conserve resources.
• Retry Logic -- Automatic retry with exponential backoff (3 attempts) for transient connection failures.
• Agent Integration -- All MCP tools are surfaced as LangChain-compatible tools, available to every agent and subagent automatically.

Connectors and Integrations

CodeBuddy ships with 17 pre-configured connectors for external services. Each connector is an MCP server that can be enabled with a single click from Settings.

Jira and GitLab also have direct CLI integrations: browse tickets/issues in a VS Code quick-pick menu, create branches from selected items, and open them in the browser.

Context Pipeline

CodeBuddy gathers context from multiple sources and assembles it into each prompt automatically:

1. Active file -- The file currently open in the editor is always included.
2. @ mentions -- Reference specific files in your message with @filename to include them explicitly.
3. Semantic search -- The EmbeddingService generates vector embeddings of your codebase. The ContextRetriever performs similarity search against the vector store and falls back to keyword search if embedding is unavailable.
4. Web search -- For questions requiring external knowledge, the agent searches the web via Tavily and incorporates relevant results.
5. Codebase understanding -- A persistent, git-aware analysis service maintains an architectural map of your project (frameworks, APIs, data models, dependencies) cached in SQLite and invalidated when the git state changes.
6. Project rules -- Loaded from .codebuddy/rules.md and injected into every prompt.
7. Agent memory -- Persistent knowledge, rules, and experience from the core memory system.
8. Skills -- Custom skill definitions from .codebuddy/skills/ are appended to the system prompt.
9. Reader context -- If an article is open in the Smart Reader, its content is available to the agent.
10. Question classification -- An NLP-based classifier (using stemming and fuzzy matching) categorizes each query to optimize which context sources are prioritized.

The EnhancedPromptBuilderService assembles the final prompt from these sources, respecting the configured token budget and deduplicating by file path.

Project Rules and Skills

Project Rules

Define how CodeBuddy writes code for your project. Rules are automatically loaded and injected into every AI prompt.

• File locations: .codebuddy/rules.md, .codebuddy/rules/index.md, .codebuddyrules, or CODEBUDDY.md
• Directory rules: Place multiple .md files in .codebuddy/rules/ and they are merged together.
• Token budget: Configurable maximum (default 2000 tokens) with smart truncation if rules exceed the limit.
• Settings-based rules: Define additional rules and a custom system prompt directly in the VS Code settings UI.
• Live reload: File watchers detect changes and reload rules automatically.
• Template scaffolding: The Init Rules command creates a starter template.

Skills

Extend the agent's capabilities with custom skills:

• Place any *SKILL.md file in the .codebuddy/skills/ directory.
• Each skill file uses YAML frontmatter to define a name and description.
• Skills are automatically discovered (including subdirectories) and appended to the agent's system prompt.
• The agent can then invoke the skill's described behavior when relevant.

Persistent Memory

The agent maintains memory across sessions using a file-backed storage system at .codebuddy/memory.json:

• Three categories: Knowledge (facts and information), Rule (behavioral guidelines), Experience (lessons learned from past interactions).
• Two scopes: User (global, persists across all workspaces) and Project (workspace-specific).
• CRUD operations: The agent can add, update, delete, and search memories during execution.
• System prompt injection: All stored memories are automatically included in the agent's context.

The agent also has a persistent task manager (.codebuddy/tasks.json) for tracking work items with priorities and statuses across sessions.

Coworker Automations

CodeBuddy runs scheduled background tasks that surface actionable information without requiring manual invocation:

All automations can be triggered manually from the Command Palette or disabled individually from Settings.

Smart Reader

CodeBuddy includes a built-in distraction-free article reader:

• Extracts article content using Mozilla Readability with DOMPurify sanitization.
• Renders in a dedicated VS Code webview panel.
• Caches articles for 24 hours (up to 100 articles) to avoid redundant fetches.
• Maintains a browsing history accessible from the toolbar.
• Three modes: Smart Reader (built-in, recommended), Simple Browser, or System Browser.
• Article content is available to the agent as context, so you can ask questions about what you are reading.

Observability

CodeBuddy ships with built-in OpenTelemetry instrumentation:

• Tracing: OpenTelemetry SDK with in-memory span exporter for local debugging. OpenLLMetry (Traceloop) captures LangGraph and LangChain trace data.
• Metrics: OTLP HTTP export for metrics collection.
• Structured Logging: Multi-level logging (DEBUG, INFO, WARN, ERROR) to console and file.
• Webview Panel: A dedicated Observability panel in the sidebar displays traces, logs, and system performance data in real time.

Internationalization

The interface is available in 7 languages. The language can be changed from Settings > General without restarting.

Both the webview UI (via i18next) and the extension backend (via @vscode/l10n) are fully localized. Right-click context menu commands follow VS Code's display language setting.

Settings

Access the full settings panel via the gear icon in the sidebar. Settings are organized into sections:

Installation

Install from either registry:

• VS Code Marketplace
• Open VSX Registry

Or search for "CodeBuddy" in the VS Code extension manager.

Configuration

Cloud Providers

1. Open the CodeBuddy sidebar and click the gear icon to open Settings.
2. Navigate to the Models section.
3. Select your preferred AI provider.
4. Enter your API key.

Local Models (Ollama)

{
  "generativeAi.option": "Local",
  "local.baseUrl": "http://localhost:11434/v1",
  "local.model": "qwen2.5-coder"
}

Local Models (Docker)

docker compose -f docker-compose.yml up -d
docker exec -it ollama ollama pull qwen2.5-coder

Docker Model Runner is also supported for running models through Docker Desktop's built-in model runtime at localhost:12434.

MCP Servers

Configure MCP servers in VS Code settings under codebuddy.mcpServers. Example:

{
  "codebuddy.mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {}
    }
  }
}

Or enable the Docker MCP Gateway for a unified catalog of tools managed through Docker Desktop.

Data Storage

CodeBuddy stores all data locally in a .codebuddy directory at your workspace root:

• chat-history/ -- Conversation logs in JSON format
• memory.json -- Persistent agent knowledge, rules, and experience
• tasks.json -- Task tracking data
• analysis.db -- SQLite database for codebase analysis snapshots
• rules.md -- Project-specific behavior rules
• skills/ -- Custom skill definitions
• Logs and session state

This directory is automatically added to .gitignore.

Troubleshooting

Local model not connecting

• Verify Ollama is running (ollama serve or check Docker container status).
• Confirm the port: 11434 for Ollama, 12434 for Docker Model Runner.
• Check that local.baseUrl matches your setup.

Agent not responding

• Click the Stop button in the chat interface.
• Clear chat history from Settings > Privacy.
• Check the CodeBuddy output channel: View > Output > CodeBuddy.

API key errors

• Verify the key is entered correctly in Settings > Models.
• Confirm the selected model matches the provider for your key.
• Check network connectivity for cloud providers.

MCP server not connecting

• Verify the server command is installed and accessible.
• Check the MCP server logs in the output channel.
• For Docker Gateway, ensure Docker Desktop is running.

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines on setting up the development environment, running tests, and submitting pull requests.

License

MIT License -- see LICENSE for details.

Repository