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
AbortSignalor 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/finallyin the agent service ensures slots are always returned, even on stream failure or cancellation.