--- sidebar_position: 3 title: "Development Environment" --- # Development Environment 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. ## Prerequisites Before you begin, make sure you have the following installed: 1. **Git** - For version control 2. **Node.js** (version [v20.18.1](https://github.com/Kilo-Org/kilocode/blob/main/.nvmrc) or higher recommended) and npm 3. **Visual Studio Code** - Our recommended IDE for development ## Getting Started ### Installation 1. **Fork and Clone the Repository**: - **Fork the Repository**: - Visit the [Kilo Code GitHub repository](https://github.com/Kilo-Org/kilocode) - Click the "Fork" button in the top-right corner to create your own copy. - **Clone Your Fork**: ```bash git clone https://github.com/[YOUR-USERNAME]/kilocode.git cd kilocode ``` Replace `[YOUR-USERNAME]` with your actual GitHub username. 1. **Install dependencies**: ```bash pnpm install ``` This command will install dependencies for the main extension, webview UI, and e2e tests. 1. **Install VSCode Extensions**: - **Required**: [ESBuild Problem Matchers](https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers) - Helps display build errors correctly. While not strictly necessary for running the extension, these extensions are recommended for development: - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Integrates ESLint into VS Code. - [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Integrates Prettier into VS Code. The full list of recommended extensions is [here](https://github.com/Kilo-Org/kilocode/blob/main/.vscode/extensions.json) ### Project Structure The project is organized into several key directories: - **`src/`** - Core extension code - **`core/`** - Core functionality and tools - **`services/`** - Service implementations - **`webview-ui/`** - Frontend UI code - **`e2e/`** - End-to-end tests - **`scripts/`** - Utility scripts - **`assets/`** - Static assets like images and icons ## Development Workflow ### Building the Extension To build the extension: ```bash pnpm build ``` This will: 1. Build the webview UI 2. Compile TypeScript 3. Bundle the extension 4. Create a `.vsix` file in the `bin/` directory ### Running the Extension To run the extension in development mode: 1. Press `F5` (or select **Run** → **Start Debugging**) in VSCode 2. This will open a new VSCode window with Kilo Code loaded ### Hot Reloading - **Webview UI changes**: Changes to the webview UI will appear immediately without restarting - **Core extension changes**: Changes to the core extension code will automatically reload the ext host In development mode (NODE_ENV="development"), changing the core code will trigger a `workbench.action.reloadWindow` command, so it is no longer necessary to manually start/stop the debugger and tasks. > **Important**: In production builds, when making changes to the core extension, you need to: > > 1. Stop the debugging process > 2. Kill any npm tasks running in the background (see screenshot below) > 3. Start debugging again Stopping background tasks ### Installing the Built Extension To install your built extension: ```bash code --install-extension "$(ls -1v bin/kilo-code-*.vsix | tail -n1)" ``` Replace `[version]` with the current version number. ## Testing Kilo Code uses several types of tests to ensure quality: ### Unit Tests Run unit tests with: ```bash npm test ``` This runs both extension and webview tests. To run specific test suites: ```bash npm run test:extension # Run only extension tests npm run test:webview # Run only webview tests ``` ### End-to-End Tests E2E tests verify the extension works correctly within VSCode: 1. Create a `.env.local` file in the root with required API keys: ``` OPENROUTER_API_KEY=sk-or-v1-... ``` 2. Run the integration tests: ```bash npm run test:integration ``` For more details on E2E tests, see [e2e/VSCODE_INTEGRATION_TESTS.md](https://github.com/Kilo-Org/kilocode/blob/main/e2e/VSCODE_INTEGRATION_TESTS.md). ## Linting and Type Checking Ensure your code meets our quality standards: ```bash npm run lint # Run ESLint npm run check-types # Run TypeScript type checking ``` ## Git Hooks This project uses [Husky](https://typicode.github.io/husky/) to manage Git hooks, which automate certain checks before commits and pushes. The hooks are located in the `.husky/` directory. ### Pre-commit Hook Before a commit is finalized, the `.husky/pre-commit` hook runs: 1. **Branch Check**: Prevents committing directly to the `main` branch. 2. **Type Generation**: Runs `npm run generate-types`. 3. **Type File Check**: Ensures that any changes made to `src/exports/roo-code.d.ts` by the type generation are staged. 4. **Linting**: Runs `lint-staged` to lint and format staged files. ### Pre-push Hook Before changes are pushed to the remote repository, the `.husky/pre-push` hook runs: 1. **Branch Check**: Prevents pushing directly to the `main` branch. 2. **Compilation**: Runs `npm run compile` to ensure the project builds successfully. 3. **Changeset Check**: Checks if a changeset file exists in `.changeset/` and reminds you to create one using `npm run changeset` if necessary. These hooks help maintain code quality and consistency. If you encounter issues with commits or pushes, check the output from these hooks for error messages. ## Troubleshooting ### Common Issues 1. **Extension not loading**: Check the VSCode Developer Tools (Help > Toggle Developer Tools) for errors 2. **Webview not updating**: Try reloading the window (Developer: Reload Window) 3. **Build errors**: Make sure all dependencies are installed with `npm run install:all` ### Debugging Tips - Use `console.log()` statements in your code for debugging - Check the Output panel in VSCode (View > Output) and select "Kilo Code" from the dropdown - For webview issues, use the browser developer tools in the webview (right-click > "Inspect Element")