🎼 CodeConductor

Full session lifecycle: start, heartbeat, pause, redirect, end, and cancel. Sessions are persisted to SQLite and surfaced in the VS Code tree view and dashboard in real time.

• Sessions include agent name, model tier, file-lock intent, and token budget
• Stale sessions auto-expire after a configurable inactivity window
• Multiple agents can hold concurrent sessions; the dashboard shows all active sessions

Prevents concurrent agents from editing the same files. Supports two enforcement modes configurable per repo:

• warn — conflicting agent receives a warning but is not blocked
• block — second agent cannot acquire the lock until the first releases it
• Exclusive and shared lock modes (read-only vs. write intent)
• Lock state is visible in the sidebar under the "Locks" tree node

Agents create structured handoff objects to pass work to other agents or human reviewers. Supports priority queuing, pipeline chains, and model-tier recommendations.

• Handoffs include title, description, priority, required capabilities, and context snapshot
• Pipeline chains allow sequential agent workflows to auto-advance
• Incoming PM tip: handoffs are the primary mechanism for agent-to-agent task delegation

Two dashboard surfaces: a compact sidebar panel and a full-screen editor panel. Both show live agent sessions, file locks, handoffs, and health status.

• Sidebar: compact view, always visible in the Activity Bar
• Full panel: detailed session cards, lock tables, handoff queue
• Human intervention controls: pause, redirect, end, claim handoff from the UI

Standalone MCP server exposing 24 cc_* tools over stdio transport. Any MCP-compatible AI agent can connect without the VS Code extension being present.

• Groups: Sessions (7), Locks (3), Handoffs (5), Agents (3), Context & Budget (6)
• Compatible clients: Claude Code, GitHub Copilot (MCP preview), Cursor, any MCP SDK client

Over 100 Markdown agent templates organized into 10 categories. Templates define agent personality, capabilities, and tool-use preferences.

• Categories: Engineering, Design, Marketing, Product, Project Management, Strategy, Support, Testing, Specialized, Spatial Computing
• Used by cc_match_agents and cc_get_agent_prompt to build system prompts

Per-session token accounting with configurable budget limits and warning thresholds. Agents can query remaining budget before performing expensive operations.

• VS Code settings: codebuddy.tokenBudget.maxTokensDefault (default 120 000)
• Warning fires at codebuddy.tokenBudget.sessionDurationWarningMinutes
• Budget-aware model tier recommendations via cc_get_model_recommendation

Compresses the current workspace state into a handoff-friendly context object. AST context extraction (via Tree-sitter) scopes context to the relevant code symbols rather than whole files.

• Supports JS, JSX, TS, TSX out of the box
• Capsule saved to .codebuddy/context-capsule.json

A project-local knowledge base that agents can read and write. Implemented as structured Markdown files under .codebuddy/wiki/. Inspired by the Karpathy LLM Wiki pattern.

• Survives session boundaries — knowledge persists across agent restarts
• Added in v0.2.0 alongside the external dashboard WebSocket server

Tracks build, test, and deploy health across the workspace. Health state is emitted at session end and surfaced in the dashboard.

• Agents record health outcomes; the dashboard shows a traffic-light view
• Run via cc_end_session — health checks fire automatically

Per-repo settings in .codebuddy.json control locking behavior, tool gating, wiki, token budgets, and agent routing preferences. Supports a legacy .codeconductor.json path as well.

A lightweight WebSocket server (ws) that allows external browser or tooling clients to subscribe to real-time CodeConductor state events without running inside VS Code.

• Useful for CI dashboards, team overview screens, and non-VS Code agents
• Implementation: src/extension/websocket-server.js

What's broken: npm run lint fails with a no-case-declarations error in src/extension/dashboard-actions.js line 80. A const is declared inside a case block without braces. Two additional no-unused-vars warnings exist in dashboard-provider.js.

Impact: The Husky pre-commit hook would fail on any committer's machine. The extension works at runtime — this is a lint-level issue only.

Fix: Wrap the offending case block in {}. Two-minute change. Remove or prefix unused vars with _.

What's missing: Unit tests exist for dashboard model, actions, and HTML generation. However, the sidebar webview (dashboard-provider.js) and full panel (dashboard-panel.js, webview/dashboard.js) have no end-to-end rendering tests.

Impact: UI changes can silently break the webview with no test failure. This is the most significant quality gap before a Marketplace publish.

Approach candidates: @vscode/test-electron integration runner, or a lightweight webview screenshot harness.

What's wrong: Three files with local Windows absolute paths were committed: lint-results.json, lint-results.txt, lint.json. These are development artifacts that should be in .gitignore.

Impact: Noise for other developers. Will expose contributor machine paths in git history.

Fix: Add to .gitignore, remove from tracking with git rm --cached.

What's missing: The 24 MCP server tool handlers (src/server/tools/) and the resource layer (src/server/resources.js) lack a dedicated test suite. Core library behavior is well-covered, but the MCP transport + tool dispatch layer is tested only indirectly.

Impact: A regression in an MCP tool handler could ship without a failing test. Medium risk given the stable core underneath.

What's slow: Every write to the SQLite store calls db.export() + fs.writeFileSync() synchronously, blocking the Node.js event loop. Documented in docs/IMPLEMENTATION-PLAN.md.

Impact: Measurable latency with 10+ concurrent agents. Not a problem in single-agent or low-frequency use cases.

Proposed fix: Debounced async write queue with ~300ms batching. src/core/store.js is the only file to change.

The README.md links to docs/TROUBLESHOOTING.md and docs/ROADMAP.md. One or both may be absent or stub-only. This creates broken links for first-time users reading the README.

Fix: Either create the missing docs or update the README to remove/replace the links. Tracked as TEA-244.

Phase 4 (Real-time Dashboard + Human Oversight) is marked In Progress in Linear. The dashboard surfaces exist and render correctly, but the phase definition included release-grade smoke coverage and gap validation between current UI and original spec — those are still open (TEA-242 is the child issue).

The packaged codeconductor-0.1.0.vsix exists in the repo root and the CHANGELOG documents v0.1.0. However, the GitHub release has not been published and the extension has not been submitted to the VS Code Marketplace. Both are open Todo items in Linear.

Note: The repo is now at v0.2.0 on master, meaning the next publish will need to decide whether to backfill v0.1.0 or publish v0.2.0 directly.

Debounced async write queue for SQLite persistence, eliminating the synchronous writeFileSync on every state change. Estimated 2–4 hour implementation in src/core/store.js.

Dedicated src/server/__tests__/tools.test.js and resources.test.js covering all 24 MCP tools and the resource exposure layer. Framework exists — needs test authoring.

Event-driven routing engine that automatically dispatches work between agents. Listens for session_end and handoff_created events, evaluates routing rules from config, and advances pipeline chains. Tracked in Linear as Todo.

• Capability-based agent matching
• Priority + round-robin ranking
• Config-driven routing rules

Separate the dashboard into a standalone React/Vite frontend application backed by an Express server. This would enable team-wide dashboards running outside of VS Code — on a shared monitor, CI display, or web portal.

WebSocket-driven collaborative dashboard where multiple team members and agents see the same live view. The WebSocket server foundation exists in v0.2.0; the full collaborative UI is v2.0 scope.

Dashboard charts showing token usage per agent, handoff completion rates, session duration distributions, and model tier efficiency metrics. Backend tracking already exists — UI is the gap.

Visual prediction of token burn rate based on session history. The per-session tracking backend is complete in src/core/token-budget.js; the forecasting chart layer is deferred to v2.0.

Replace sql.js (in-memory WASM SQLite) with a native SQLite binding (better-sqlite3 or equivalent) to unlock proper transaction isolation and WAL mode for high-concurrency scenarios.