mirror of
https://github.com/Kilo-Org/kilocode.git
synced 2026-10-30 19:32:39 +08:00
docs: Update dev setup instructions (#10508)
This commit is contained in:
Johnny Eric Amancio
+61
-1
@@ -42,13 +42,73 @@ The Kilo Community is [on Discord](https://kilo.ai/discord).
|
||||
## Developing Kilo CLI
|
||||
|
||||
- **Requirements:** Bun 1.3.13+, Java 21 (see [Prerequisites](#prerequisites) above)
|
||||
- Install dependencies and start the dev server from the repo root:
|
||||
- Install dependencies and start the CLI from the repo root:
|
||||
|
||||
```bash
|
||||
bun install
|
||||
bun dev
|
||||
```
|
||||
|
||||
`bun dev` and `bun run dev` both run the local CLI. For the VS Code extension, use `bun run extension`.
|
||||
|
||||
## Common Checks
|
||||
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
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 so tests run from the package that owns them.
|
||||
|
||||
### CLI checks
|
||||
|
||||
From `packages/opencode/`:
|
||||
|
||||
```bash
|
||||
bun run typecheck
|
||||
bun test
|
||||
bun test ./path/to/file.test.ts
|
||||
```
|
||||
|
||||
For backend/API validation, see [`TESTING.md`](./TESTING.md). It covers starting the local backend with `bun dev serve` and making `curl` requests against it. After changing server endpoints in `packages/opencode/src/server/`, run `./script/generate.ts` from the repo root to regenerate `packages/sdk/js/`.
|
||||
|
||||
### VS Code extension checks
|
||||
|
||||
From `packages/kilo-vscode/`:
|
||||
|
||||
```bash
|
||||
bun run typecheck
|
||||
bun run lint
|
||||
bun run test:unit
|
||||
bun run test
|
||||
bun run compile
|
||||
bun run package
|
||||
```
|
||||
|
||||
### Documentation checks
|
||||
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
bun run --filter @kilocode/kilo-docs test
|
||||
bun run --filter @kilocode/kilo-docs build
|
||||
bun run --filter @kilocode/kilo-docs dev
|
||||
```
|
||||
|
||||
For manual docs validation, run the docs site locally, preview the affected page, and check changed links and rendered content.
|
||||
|
||||
### Guardrails
|
||||
|
||||
- User-facing changes usually need a changeset (`bunx changeset add` or a file under `.changeset/`).
|
||||
- After changing server endpoints, regenerate the SDK with `./script/generate.ts`.
|
||||
- After adding or changing guarded URLs in `packages/kilo-vscode/`, `packages/kilo-vscode/webview-ui/`, or `packages/opencode/src/`, run `bun run script/extract-source-links.ts` from the repo root.
|
||||
- When editing shared `packages/opencode/` files, keep Kilo 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.
|
||||
|
||||
### Developing the VS Code Extension
|
||||
|
||||
Build and launch the extension in an isolated VS Code instance:
|
||||
|
||||
@@ -16,8 +16,9 @@ This document will help you set up your development environment and understand h
|
||||
Before you begin, make sure you have the following installed:
|
||||
|
||||
1. **Git** - For version control
|
||||
2. **Node.js** (version v20.18.1 (See `.nvmrc` for latest) or higher recommended) and npm
|
||||
2. **Bun 1.3.13+** - Required for installing dependencies and running scripts
|
||||
3. **Visual Studio Code** - Our recommended IDE for development
|
||||
4. **Java 21** - Required only when running JetBrains plugin checks or repo-level checks that include `@kilocode/kilo-jetbrains`
|
||||
|
||||
## Getting Started
|
||||
|
||||
@@ -37,10 +38,10 @@ Before you begin, make sure you have the following installed:
|
||||
1. **Install dependencies**:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
bun install
|
||||
```
|
||||
|
||||
This command will install dependencies for the main extension, webview UI, and e2e tests.
|
||||
This command will install dependencies for all workspace packages.
|
||||
|
||||
1. **Install VSCode Extensions**:
|
||||
- **Required**: [ESBuild Problem Matchers](https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers) - Helps display build errors correctly.
|
||||
@@ -54,134 +55,128 @@ The full list of recommended extensions is in `.vscode/extensions.json`
|
||||
|
||||
### Project Structure
|
||||
|
||||
The project is organized into several key directories:
|
||||
The project is organized into several key packages:
|
||||
|
||||
- **`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
|
||||
- **`packages/opencode/`** - Kilo CLI, agent runtime, local HTTP server, session management, and TUI
|
||||
- **`packages/kilo-vscode/`** - VS Code extension, webview UI, Agent Manager, and extension packaging
|
||||
- **`packages/sdk/js/`** - Generated TypeScript SDK for the local server API
|
||||
- **`packages/kilo-docs/`** - Documentation site
|
||||
- **`packages/kilo-jetbrains/`** - JetBrains plugin
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Building the Extension
|
||||
### Running the CLI
|
||||
|
||||
To build the extension:
|
||||
To run the CLI from the repo root:
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
bun dev
|
||||
```
|
||||
|
||||
This will:
|
||||
`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.
|
||||
|
||||
1. Build the webview UI
|
||||
2. Compile TypeScript
|
||||
3. Bundle the extension
|
||||
4. Create a `.vsix` file in the `bin/` directory
|
||||
### Backend/API Validation
|
||||
|
||||
For backend and API validation, use the root [TESTING.md](https://github.com/Kilo-Org/kilocode/blob/main/TESTING.md) guide. It covers starting the local backend with:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
./script/generate.ts
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
{% image src="https://github.com/user-attachments/assets/466fb76e-664d-4066-a3f2-0df4d57dd9a4" alt="Stopping background tasks" width="600" /%}
|
||||
|
||||
### Installing the Built Extension
|
||||
|
||||
To install your built extension:
|
||||
|
||||
```bash
|
||||
code --install-extension "$(ls -1v bin/kilo-code-*.vsix | tail -n1)"
|
||||
bun run extension
|
||||
```
|
||||
|
||||
Replace `[version]` with the current version number.
|
||||
This will build and launch the extension in an isolated VS Code instance.
|
||||
|
||||
### Building the Extension
|
||||
|
||||
From `packages/kilo-vscode/`:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## Testing
|
||||
|
||||
Kilo Code uses several types of tests to ensure quality:
|
||||
|
||||
### Unit Tests
|
||||
### Repo-Level Checks
|
||||
|
||||
Run unit tests with:
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
npm test
|
||||
bun install
|
||||
bun run lint
|
||||
bun run typecheck
|
||||
```
|
||||
|
||||
This runs both extension and webview tests.
|
||||
`bun run typecheck` wraps `bun turbo typecheck`. Use `bun turbo typecheck --force` if you need to bypass the Turbo cache.
|
||||
|
||||
To run specific test suites:
|
||||
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.
|
||||
|
||||
### CLI Checks
|
||||
|
||||
From `packages/opencode/`:
|
||||
|
||||
```bash
|
||||
npm run test:extension # Run only extension tests
|
||||
npm run test:webview # Run only webview tests
|
||||
bun run typecheck
|
||||
bun test
|
||||
bun test ./path/to/file.test.ts
|
||||
```
|
||||
|
||||
### End-to-End Tests
|
||||
Use the root [TESTING.md](https://github.com/Kilo-Org/kilocode/blob/main/TESTING.md) guide for backend/API checks that require `bun dev serve` and `curl`-based requests.
|
||||
|
||||
E2E tests verify the extension works correctly within VSCode:
|
||||
### VS Code Extension Checks
|
||||
|
||||
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
|
||||
|
||||
## Linting and Type Checking
|
||||
|
||||
Ensure your code meets our quality standards:
|
||||
From `packages/kilo-vscode/`:
|
||||
|
||||
```bash
|
||||
npm run lint # Run ESLint
|
||||
npm run check-types # Run TypeScript type checking
|
||||
bun run typecheck
|
||||
bun run lint
|
||||
bun run test:unit
|
||||
bun run test
|
||||
bun run compile
|
||||
bun run package
|
||||
```
|
||||
|
||||
### Documentation Checks
|
||||
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- User-facing changes usually need a changeset. Run `bunx changeset add` or add a file under `.changeset/`.
|
||||
- After changing server endpoints, run `./script/generate.ts` from the repo root to regenerate `packages/sdk/js/`.
|
||||
- After adding or changing guarded URLs in `packages/kilo-vscode/`, `packages/kilo-vscode/webview-ui/`, or `packages/opencode/src/`, run `bun run script/extract-source-links.ts` from the repo root.
|
||||
- When editing shared `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.
|
||||
|
||||
## 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.
|
||||
This project uses [Husky](https://typicode.github.io/husky/) to manage Git hooks. The current pre-push hook checks the Bun version against root `package.json` and runs the repo-level typecheck.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -189,7 +184,8 @@ These hooks help maintain code quality and consistency. If you encounter 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`
|
||||
3. **Build errors**: Make sure all dependencies are installed with `bun install`
|
||||
4. **Root tests fail immediately**: This is expected. Run package-level tests instead of root `bun test`
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
|
||||
@@ -85,13 +85,23 @@ Guidelines:
|
||||
|
||||
Skip the changeset only for internal refactors, CI tweaks, test-only changes, or docs that do not affect users.
|
||||
|
||||
### Other Guardrails
|
||||
|
||||
- Regenerate `packages/sdk/js/` with `./script/generate.ts` after changing server endpoints.
|
||||
- Run `bun run script/extract-source-links.ts` after adding or changing guarded URLs in `packages/kilo-vscode/`, `packages/kilo-vscode/webview-ui/`, or `packages/opencode/src/`.
|
||||
- When editing shared `packages/opencode/` files, keep Kilo 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.
|
||||
|
||||
### Testing Your Changes
|
||||
|
||||
- Run the test suite:
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
- Manually test your changes in the development extension
|
||||
Use the current Bun commands in the [Development Environment](/docs/contributing/development-environment) guide for repo-level, CLI, backend/API, VS Code extension, and docs checks.
|
||||
|
||||
Key reminders:
|
||||
|
||||
- Do **not** run `bun test` from the repo root. The root test script intentionally exits with failure so tests run from the package that owns them.
|
||||
- Use the root [TESTING.md](https://github.com/Kilo-Org/kilocode/blob/main/TESTING.md) guide for backend/API validation with `bun dev serve` and `curl`-based requests.
|
||||
- Regenerate the SDK with `./script/generate.ts` from the repo root after changing server endpoints.
|
||||
- Manually verify extension behavior with `bun run extension`.
|
||||
- For manual documentation validation, preview the affected page and check changed links and rendered content.
|
||||
|
||||
### Creating a Pull Request
|
||||
|
||||
@@ -143,14 +153,16 @@ Documentation improvements are highly valued contributions:
|
||||
- Use absolute paths starting from `/docs/` for internal links (except within the same directory)
|
||||
- Don't include `.md` extensions in links
|
||||
|
||||
2. Test your documentation changes by running the docs site locally:
|
||||
2. Test your documentation changes and run the docs site locally from the repo root:
|
||||
|
||||
```bash
|
||||
cd packages/kilo-docs
|
||||
pnpm install
|
||||
pnpm dev
|
||||
bun run --filter @kilocode/kilo-docs test
|
||||
bun run --filter @kilocode/kilo-docs build
|
||||
bun run --filter @kilocode/kilo-docs dev
|
||||
```
|
||||
|
||||
For manual validation, preview the affected page and check changed links and rendered content.
|
||||
|
||||
3. Submit a PR with your documentation changes
|
||||
|
||||
## Community Guidelines
|
||||
|
||||
Reference in New Issue
Block a user