Contributing

MIT-licensed. Bug fixes, features, docs, and translations all welcome.

Main repo: github.com/olasunkanmi-SE/codebuddy. This docs site: codebuddy-docs.

Full contributor guide lives in the main repo’s CONTRIBUTING.md. This page is a shorter reference.

Setup

Requirements: Node.js 20+, Git, VS Code (or Cursor / Windsurf / VSCodium).

git clone https://github.com/<you>/codebuddy.git
cd codebuddy
npm ci
cd webviewUi && npm ci && cd ..

Two package.jsons exist — root is the extension host, webviewUi/ is the React webview. Both need npm ci.

Dev loop

npm run watch          # tsc --watch (extension host)
npm run dev:webview    # in another terminal — Vite dev for the webview

Press F5 to launch an Extension Development Host with CodeBuddy loaded.

Project layout

Directory	Contents
src/	Extension source (TypeScript)
src/agents/	LangGraph agent, subagents, tool providers
src/services/	Core services (indexing, testing, embedding, …)
src/webview-providers/	Webview ↔ extension message handlers
src/workers/	Worker threads (AST, embedding, codebase analysis)
src/infrastructure/	Logger, telemetry, observability
src/MCP/	MCP protocol integration
webviewUi/	Webview frontend (separate npm project)
skills/	Built-in skill definitions (SKILL.md)
l10n/	Translation bundles
.github/	CI workflows, issue/PR templates

Scripts

Script	Purpose
npm run compile	tsc typecheck (extension host)
npm run watch	tsc watch mode
npm run compile:test	Compile test files
npm run lint	ESLint on src/. Must exit 0. CI gates on it.
npm run fix	ESLint auto-fix
npm run format	Prettier
npm run test:unit	Pure-mocha unit tests, ~60 ms end-to-end. No VS Code boot.
npm test	vscode-test full run (xvfb on Linux in CI)
npm run build:webview	Build the webview
npm run dev:webview	Vite dev server for the webview
npm run package	esbuild production bundle
npm run build	Full: compile + format + build:webview + package

Tests

Two harnesses, kept separate:

• .unit.test.ts → npm run test:unit. Pure mocha, no VS Code. Fast. If your code can be tested here, do it here.
• .test.ts (no .unit.) → npm test. vscode-test boots a full VS Code instance under xvfb. Slower.

Rule of thumb: unit-test what can be tested without VS Code; use vscode-test only for genuine integration paths (WASM boot, real vscode.* API).

Coding standards

• TypeScript strict — no any in new code without a comment.
• ESLint must exit 0 (warnings allowed).
• Prettier for formatting.
• File names kebab-case.ts for source, PascalCase.tsx for React.
• Singletons use _resetForTesting() for test lifecycles — see WorkspaceIdentityService, MCPApprovalService, SecondaryLLMService for the pattern.
• DI seams over mocks — for services that need pure-Node testability, expose _configureForTesting(deps) that swaps production deps. SecondaryLLMService is the reference.

Security invariants (must-know)

The main-repo CLAUDE.md §5 lists 18. Top 8 for new contributors:

1. Never shell: true in spawn(). Ever.
2. Always execFile for git and other CLIs with user-influenced args.
3. Terminal.executeAnyCommand is the only path for LLM-issued shell commands. Don’t add a second.
4. Every LLM-controlled file path goes through WorkspaceIdentityService.validatePathWithinWorkspace(), using the returned resolved path.
5. DOMPurify-sanitize anything from LLM output that becomes HTML.
6. No "default": "apiKey" (or placeholder string) in package.json config defaults — use null.
7. QuickJS is the only sandboxed-code path. No eval, new Function, vm.runInContext.
8. No QuickJS host binding may call write-side tools or reach through an approval gate.

Every PR touching those areas exercises the security checkboxes in .github/PULL_REQUEST_TEMPLATE.md.

Branches + PRs

• development — active work. Branch off here.
• main — stable releases. PRs development → main cut releases.

PR flow:

1. Fork.
2. git checkout -b feature/my-feature development.
3. Implement + test.
4. npm run compile && npm run lint && npm run test:unit — all green.
5. Push, open PR against development.

Commit style: Conventional-commits-ish — type(scope): subject, imperative, under 72 chars. Body explains why.

CI

Every PR runs a matrix on Ubuntu, Windows, macOS:

1. Checkout + diff.
2. Node 20 setup + npm ci.
3. Security audit.
4. Lint → compile → format.
5. Build webview (npm ci && lint && build in webviewUi/).
6. Compile tests → test:unit + vscode-test (xvfb on Linux).
7. Coverage upload — 30% minimum line coverage threshold.
8. Package.

Release process

Tag-driven:

git tag v4.3.0
git push origin v4.3.0

Deploy pipeline builds + publishes to VS Code Marketplace and Open VSX; creates a GitHub Release with the .vsix attached.

Docs

Docs site is separate: codebuddy-docs. Astro Starlight; markdown files under src/content/docs/.

git clone https://github.com/olasunkanmi-SE/codebuddy-docs.git
cd codebuddy-docs
npm ci
npm run dev

Reporting issues

GitHub Issues — include OS, editor + version, CodeBuddy version, minimal repro, expected vs actual, relevant Output > CodeBuddy logs. For security: don’t open a public issue — see SECURITY.md.

Dependencies

Dependabot manages updates:

Scope	Cadence	PR limit
Root npm	Weekly	10
webviewUi/ npm	Weekly	5
GitHub Actions	Monthly	—

Code of Conduct

CODE_OF_CONDUCT.md in the main repo.