DEPRECATION NOTICE

Active development for CodeBuddy has officially moved to a private repository. This public repository is now archived and will no longer accept new features, bug fixes, issues, or pull requests (including automated dependency updates).

Thank you to everyone who supported and interacted with the public version of this project!

CodeBuddy

Autonomous AI Software Engineer for Visual Studio Code

Read the DOCS

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 10 AI providers (cloud and local), over 20 built-in tools, 16 bundled skill integrations, a Model Context Protocol gateway for unlimited extensibility, enterprise-grade security controls, and full internationalization in 7 languages.

Table of Contents

• Architecture

• Agent System

• Concurrency and Queue Management

• Operating Modes

• AI Providers

• Provider Failover

• Built-in Tools

• Commands

• Inline Code Completion

• Diff Review System

• Model Context Protocol (MCP)

• Connectors and Integrations

• Skills System

• Context Pipeline

• Hybrid Memory and Search

• Project Rules

• Security

• Coworker Automations

• Cost Tracking

• Smart Reader

• Observability

• Internationalization

• Settings Reference

• 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
    --> ConcurrencyQueueService gates admission (priority-aware semaphore)
    --> 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
          --> AgentSafetyGuard enforces event/tool/duration limits
          --> ProviderFailoverService retries on alternate providers
        --> 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

Layer Mechanism Purpose

In-memory cache TTL-based Map (Memory singleton) Session data, model references, transient state

File storage .codebuddy/ workspace directory Agent state snapshots, memories, tasks, rules

SQLite sql.js (WASM) with FTS4 full-text search Codebase analysis, persistent structured data, keyword search

LangGraph checkpointer SqljsCheckpointSaver (SQLite-backed) Multi-turn conversation threads with resumable state

VS Code SecretStorage Encrypted OS keychain API keys and credentials

Vector store SqliteVectorStore with pre-normalized vectors Workspace embeddings for semantic search

Credential proxy In-process HTTP proxy on 127.0.0.1 Session-token-authenticated credential injection for LLM SDK

Tree-Sitter Language Support

CodeBuddy uses Tree-sitter WASM binaries for accurate AST parsing across 7 languages, powering codebase analysis, symbol extraction, and the code indexing worker thread:

Language Binary

JavaScript tree-sitter-javascript.wasm

TypeScript tree-sitter-tsx.wasm

Python tree-sitter-python.wasm

Go tree-sitter-go.wasm

Java tree-sitter-java.wasm

Rust tree-sitter-rust.wasm

PHP tree-sitter-php.wasm

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:

Subagent Responsibility

Code Analyzer Deep code review, bug identification, complexity analysis, anti-pattern detection

Doc Writer Technical documentation, API references, README generation, tutorials

Debugger Error investigation, stack trace analysis, root cause identification, fix proposals

File Organizer Directory restructuring, file renaming, project layout optimization

Architect System design, pattern selection, architecture decision records, scalability planning

Reviewer Code quality enforcement, security review, best practices, style compliance

Tester Test strategy, unit/integration test generation, test execution and validation

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.

Safety Guardrails

The AgentSafetyGuard enforces hard limits on every agent stream to prevent runaway execution:

• Maximum 2,000 stream events per session (configurable up to 10,000).

• Maximum 400 tool invocations per session (configurable up to 2,000).

• Maximum 10-minute runtime per session (configurable up to 60 minutes).

• Per-tool call counting with specific caps: file edits (8), terminal commands (10), web searches (8).

• Loop detection for repeated file edits to the same file (threshold: 4).

The ProductionSafeguards service provides a circuit breaker with CLOSED/OPEN/HALF_OPEN states and 5 recovery strategies for handling sustained failures.

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.

Checkpoints

The CheckpointService saves agent execution state to SQLite, enabling resumable conversations. Before each agent operation, a named checkpoint is created so work can be restored if the session is interrupted.

Concurrency and Queue Management

The ConcurrencyQueueService controls the maximum number of concurrent agent operations. When all slots are occupied, incoming requests are queued in priority-aware FIFO order and drained as slots free up.

• Configurable concurrency limit: 1 to 10 slots (default 3), adjustable at runtime.

• Three priority levels: USER (2), SCHEDULED (1), BACKGROUND (0). Higher-priority requests are dequeued first; ties are broken by arrival time.

• Queue depth cap: Scales proportionally with the concurrency limit (10x multiplier). Requests beyond the cap are rejected with back-pressure feedback.

• Starvation prevention: Items waiting longer than 60 seconds receive an automatic priority boost, preserving fairness with stable sort.

• Cancellation: Cancel individual items or all waiting items from the QuickPick status view.

• AbortSignal support: Callers can pass an AbortSignal or a timeout for cooperative cancellation. Runtime polyfills ensure compatibility across VS Code Electron versions.

• Status bar: Displays running and queued counts. Hidden when the queue is idle.

• Guaranteed slot release: An outer try/finally in the agent service ensures slots are always returned, even on stream failure or cancellation.