A full walkthrough of every feature, how to use the ones that need your attention, and answers to the most common "why isn't this working?" moments.
CodeBuddy is a VS Code extension that acts like a traffic controller for AI agents working on your code. When you have multiple AI assistants (Claude, Copilot, Cursor, etc.) touching the same project at the same time, CodeBuddy makes sure they don't step on each other — it keeps track of who's working on what, prevents file conflicts, and helps work get handed off cleanly from one agent to the next.
Every capability, organized by what they help you accomplish.
templates/agents/ to create your own reusable agent personality..codebuddy/agent-prompt.md so any agent with file access can pick it up directly.CLAUDE.md or AGENTS.md in your workspace root so Claude Code picks it up automatically..codebuddy.json) in your project root lets you set default models, token budgets, and which tools are enabled.cc_* tools over stdio — no ports needed..codeconductor.json configs and .codeconductor/ state directories are still read automatically — nothing breaks on upgrade.These features have a yellow "You're in control" tag because they require a human decision or action. Click each one to see the exact step-by-step flow.
A session is the container for all the work one AI agent is doing right now. You start it, name it, and tell it what to achieve. Nothing is locked or tracked until a session exists.
Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac).claude-auth-refactor rather than agent1. It makes the dashboard much easier to read at a glance.Ending a session properly releases all file locks and saves a record of what was accomplished. Skipping this step leaves locks dangling and can block other agents.
CodeBuddy: Cancel Session to force-close them and release their locks.A handoff is like a sticky note left for the next person on the job — except it's structured, searchable, and can include file lists, required skills, and priority levels. The richer you make it, the less context the next agent has to re-discover.
src/components/LoginForm.tsx and src/components/LoginForm.test.tsx so they don't have to search.Claiming reserves a handoff so two agents don't start the same task at the same time. Once claimed, the handoff status changes to "claimed" and the queue updates immediately.
Sometimes an agent goes off in the wrong direction, or you need to stop it temporarily. Instead of cancelling the whole session (which releases locks and loses state), you can pause or redirect it.
cc_get_status during execution.The prompt assembly system takes the messy work out of crafting agent prompts. You describe what you need, pick a template, and CodeBuddy combines everything into a ready-to-run prompt delivered however you want.
cc_list_agents or cc_match_agents to browse templates by category or capability. See the full catalog below..codebuddy/agent-prompt.md for file-reading agents.CLAUDE.md or AGENTS.md for Claude Code.
Drop a .codebuddy.json file in your project root and CodeBuddy will use your custom defaults instead of the system defaults. You only need to do this once per project.
.codebuddy.json in your project root.codebuddy.json.{ "agentCoordination": { "budget": 60000 }, "tools": { "fileLocking": true } }Ctrl+Shift+P → Developer: Reload Window. The extension re-reads your config on startup.budget to a number lower than your AI plan's monthly token limit divided by the number of projects you're running simultaneously. This prevents any single project from consuming everything.MCP (Model Context Protocol) lets external AI tools call CodeBuddy's tools directly — the same tools available in VS Code, accessible to any connected client. No ports, no background servers required beyond the one CodeBuddy manages.
.mcp.json in your project root.mcp.json{ "mcpServers": { "codebuddy": { "command": "npx", "args": ["codebuddy-server"], "env": {} } } }cc_* tools.Ctrl+Shift+P → Welcome: Open Walkthrough → CodeBuddy: Get Started.codeconductor-server — update any references to codebuddy-server or the client won't connect.Agent templates are just Markdown files with a short header block of metadata. Drop one in the right folder and CodeBuddy automatically adds it to the catalog — no code changes needed.
.agent.md file in templates/agents/templates/agents/engineering/my-security-reviewer.agent.md. You can put it in any subfolder to organize by category.---
name: My Security Reviewer
category: engineering
description: Reviews auth and data handling.
capabilities:
- security-review
- code-review
model_tier: lead
---cc_list_agents to confirm it appears in the catalog.model_tier: lead for templates that do planning, review, or ambiguous reasoning. Use model_tier: worker for templates with well-defined, bounded tasks like formatting or test generation.Every command available from the Command Palette (Ctrl+Shift+P).
| Command | What It Does |
|---|---|
| CodeBuddy: Start Session | Register a new agent session with a name and goal. |
| CodeBuddy: End Session | Close a session cleanly, save a summary, release all locks. |
| CodeBuddy: Create Handoff | Package up work-in-progress and put it in the handoff queue. |
| CodeBuddy: Claim Next Handoff | Grab the best open handoff for the current agent based on capabilities. |
| CodeBuddy: Open Full Dashboard | Open the rich editor panel showing all sessions, handoffs, locks, and health. |
| CodeBuddy: Toggle Server | Start or stop the built-in MCP server for external client connections. |
| CodeBuddy: Quick Refresh | Force the sidebar tree and dashboard to re-read current state if the view looks stale. |
| Welcome: Open Walkthrough… | Open VS Code's guided walkthrough. Choose CodeBuddy: Get Started for the illustrated tutorial. |
Every template gives an AI a specific personality, focus, and set of capabilities. Browse by category to find the right one for your task, or use capability matching to find it automatically.
The most common "why isn't this working?" moments — and exactly how to fix them.
The extension wasn't loaded or VS Code needs a restart. Try these steps in order:
Ctrl+Shift+P → Developer: Reload Window.Ctrl+Shift+X), find CodeBuddy, and check if it shows "Enable" instead of "Disable." Click Enable..vsix file manually, make sure you reloaded VS Code after the install completed.This was a known bug fixed in version 0.1.2. Make sure you're on the latest version.
Ctrl+Shift+X) and check the CodeBuddy version number.CodeBuddy: Open Full Dashboard again.If still blank after updating: uninstall the extension completely, reinstall it, and reload.
The MCP server process failed to start. Common causes:
node --version. You need 18.0.0 or higher. If you get an error or a version below 18, install the latest LTS from nodejs.org.CodeBuddy: Toggle Server to manually restart the server process.npm run compile in the project folder first.The sidebar view may be stale. Run CodeBuddy: Quick Refresh from the Command Palette to force it to re-read the current state. If the session still doesn't appear, the session may have failed to register — try starting a new one and check the VS Code Developer Tools console (Help → Toggle Developer Tools) for errors.
Stale sessions happen when VS Code closes before the extension can clean up. To fix:
CodeBuddy: Open Full Dashboard and look for sessions with old timestamps..codebuddy/ folder from your project root and reload the window. Warning: this resets all local state including handoffs and lock history.The lock belongs to a session that ended without releasing its locks — usually because VS Code crashed. Here's how to clear it:
.codebuddy/ folder and reload VS Code. This is a full state reset, so note down any open handoffs first.CodeBuddy uses exclusive locks by default. Only one agent can hold an exclusive lock on a file at a time. Here's the flow:
App.tsx → exclusive lock granted.App.tsx → gets a LOCK_CONFLICT error with the name of the session holding the lock.There's also a shared lock mode for read-only access. Multiple agents can hold shared locks on the same file simultaneously — but a shared lock blocks exclusive locks until all shared locks are released.
The dashboard may be stale. Run CodeBuddy: Quick Refresh first. If the handoff still doesn't appear, check whether the session that created it is still active — a handoff requires an active session to be created through the VS Code commands. If you're using the MCP tools directly, verify the tool returned a handoff_id in its response with status "open".
Blocked means the AI agent couldn't proceed — there's something stopping it that requires human judgment. Escalated means the agent identified a situation beyond its capability and is asking for a higher-level decision.
Your action steps:
This shouldn't happen — claiming is atomic and the first claimant wins. But if you see duplicate work, check whether both agents called cc_claim_handoff almost simultaneously. The system will have rejected one of them with a HANDOFF_NOT_FOUND error (because it was already claimed). The agent that got the error should call cc_get_next_task to find a different open handoff instead of retrying the same one.
Your session has burned through its token budget. The default budget is 120,000 tokens per session. To fix:
.codebuddy.json: set "agentCoordination": { "budget": 250000 } and reload the window.You can check how much budget is remaining at any time with cc_get_budget_status before you hit the wall.
The session ID is generated by CodeBuddy when you run Start Session. It's returned in the response and visible in the dashboard under the session entry. It looks like a UUID — e.g., sess_a1b2c3d4e5f6. Copy it from the dashboard and include it in your instructions to the AI agent. The agent needs it to lock files, send heartbeats, and create handoffs.
Work through this checklist:
.mcp.json in the right place? It must be in the workspace root folder, not a subfolder..mcp.json say codebuddy-server? Older configs say codeconductor-server — update the args to use codebuddy-server.npx accessible? Open a terminal and run npx --version. If it fails, Node.js or npm isn't in your PATH.cc_* tools aren't showing up in my AI client's tool list. ▼The client connects to the server but isn't discovering the tools. Try:
CodeBuddy reads .codebuddy.json at startup, not on the fly. After every config change:
Ctrl+Shift+P → Developer: Reload Window.The extension will re-read the config when it activates on the next window load.
.codebuddy/ folder and now everything is gone. How do I start fresh? ▼That folder contains your local session/handoff database. Deleting it is a full reset — there's no undo. Your code files are completely untouched, only CodeBuddy's internal coordination state is gone. To start fresh:
.codebuddy/ folder and a fresh database on first use.Going forward: if you need to clear state but keep your code, this is actually the correct approach. Just note down any open handoffs manually before you do it.
.codeconductor.json config from before the rename. Do I need to update it? ▼No — CodeBuddy reads .codeconductor.json automatically as a fallback. You can continue using it indefinitely. However, if you create a new .codebuddy.json alongside it, the new file takes priority. The recommended path for new projects is .codebuddy.json, but there's no rush to migrate.
End Session is the clean path: you provide a summary of what was accomplished, the session closes gracefully, locks are released, and a record is saved for future reference. Use this whenever the agent finished its intended work.
Cancel Session is the emergency stop: it immediately terminates the session and releases all locks with no summary required. Use this when a session is stuck, the agent went off the rails, or VS Code crashed and left a zombie session behind.
Handoffs are optional but strongly recommended for anything that spans more than one agent or more than one work block. Without handoffs, the only way to transfer context between agents is by manually copying and pasting — which is exactly the kind of friction CodeBuddy is designed to eliminate.
For quick one-off tasks with a single agent, sessions alone are fine. For multi-step workflows, multi-agent pipelines, or any work that might need to be resumed later, handoffs are worth the 30 seconds it takes to create them.
The VS Code extension gives you the sidebar, dashboard, commands, and status bar — the visual, human-facing part you interact with directly in VS Code.
The MCP server is the API layer — it exposes the same coordination features as cc_* tools over the Model Context Protocol, so external AI clients like Claude Code, Cursor, and Windsurf can call them programmatically.
You need the extension to use CodeBuddy at all. The MCP server is only needed if you want external AI clients to connect and use the tools without going through the VS Code UI. Most vibe-coding workflows use both.