packages/kilo-docs/pages/contributing/development-environment.md
{% callout type="info" %}
New versions of the VS Code extension and CLI are being developed in Kilo-Org/kilocode (extension at packages/kilo-vscode, CLI at packages/opencode). For extension and CLI development, please head over to that repository.
{% /callout %}
This document will help you set up your development environment and understand how to work with the codebase. Whether you're fixing bugs, adding features, or just exploring the code, this guide will get you started.
Before you begin, make sure you have the following installed:
@kilocode/kilo-jetbrainsFork and Clone the Repository:
git clone https://github.com/[YOUR-USERNAME]/kilocode.git
cd kilocode
[YOUR-USERNAME] with your actual GitHub username.Install dependencies:
bun install
This command will install dependencies for all workspace packages.
Install VSCode Extensions:
While not strictly necessary for running the extension, these extensions are recommended for development:
The full list of recommended extensions is in .vscode/extensions.json
AI and coding agents are allowed in this repo. If you use one, start it from the repository root so the root AGENTS.md is available, then check package-specific guidance when your change touches a package with its own AGENTS.md or contributor docs.
You remain responsible for the submitted work. Before opening a PR, personally review the diff, test the change, make sure you can explain it, and understand how it interacts with the affected package and the rest of the repo. Do not use agents to submit batches of agent-generated, untested, or weakly reviewed PRs. Keep concurrent PRs limited, generally no more than three at a time, and prioritize high-impact issues first. Do not use automation or agents to mass-create issues without human review and prioritization.
Kilo has bug bounties. To be eligible, make sure your GitHub account is connected in your Kilo account.
The project is organized into several key packages:
packages/opencode/ - Kilo CLI, agent runtime, local HTTP server, session management, and TUIpackages/kilo-vscode/ - VS Code extension, webview UI, Agent Manager, and extension packagingpackages/sdk/js/ - Generated TypeScript SDK for the local server APIpackages/kilo-docs/ - Documentation sitepackages/kilo-jetbrains/ - JetBrains pluginTo run the CLI from the repo root:
bun dev
bun dev and bun run dev are equivalent. Both run the local source in packages/opencode/; they do not use a globally installed kilo binary.
For backend and API validation, use the root TESTING.md guide. It covers starting the local backend with:
bun dev serve
and validating behavior with curl requests against the local server.
If you change server endpoints in packages/opencode/src/server/, regenerate the SDK from the repo root:
./script/generate.ts
To run the extension in development mode:
bun run extension
This will build and launch the extension in an isolated VS Code instance.
From packages/kilo-vscode/:
bun run compile
bun run package
Use bun run compile when you need a development build and bun run package when you need a production extension bundle.
Kilo Code uses several types of tests to ensure quality:
From the repo root:
bun install
bun run lint
bun run typecheck
bun run typecheck wraps bun turbo typecheck. Use bun turbo typecheck --force if you need to bypass the Turbo cache.
Do not run bun test from the repo root. The root test script intentionally exits with failure to prevent accidentally running tests from the wrong package.
From packages/opencode/:
bun run typecheck
bun test
bun test ./path/to/file.test.ts
Use the root TESTING.md guide for backend/API checks that require bun dev serve and curl-based requests.
From packages/kilo-vscode/:
bun run typecheck
bun run lint
bun run test:unit
bun run test
bun run compile
bun run package
From the repo root:
bun run --filter @kilocode/kilo-docs test
bun run --filter @kilocode/kilo-docs build
bun run --filter @kilocode/kilo-docs dev
For manual documentation validation, run the docs site locally, preview the affected page, and check the changed links and rendered content.
Every PR marked ready for review must include testing evidence. A bare Not tested or N/A answer is not sufficient.
Choose checks that match the files touched. Docs-only, config-only, and similar changes may satisfy this rule with concrete manual verification or a relevant command check.
For CLI and extension changes, useful evidence can include:
For docs changes, useful evidence can include:
bun run script/check-md-table-padding.ts --fixbun run --filter @kilocode/kilo-docs testIf you cannot complete a relevant command, include all of the following in the PR:
Agent limitations, local resource constraints, OOM constraints, or an agent prompt that says to skip tests do not waive this requirement. Draft PRs may be incomplete until they are marked ready for review. Maintainers may still defer or close review at their discretion.
bunx changeset add or add a file under .changeset/../script/generate.ts from the repo root to regenerate packages/sdk/js/.packages/kilo-vscode/, packages/kilo-vscode/webview-ui/, or packages/opencode/src/, run bun run script/extract-source-links.ts from the repo root.packages/opencode/ files, keep changes small and mark Kilo-only edits with // kilocode_change for a single line or // kilocode_change start / // kilocode_change end for a block. Do not add these markers inside kilocode-named paths.This project uses Husky to manage Git hooks. The current pre-push hook checks the Bun version against root package.json and runs the repo-level typecheck.
bun installbun testconsole.log() statements in your code for debugging