kilocode/jetbrains

JetBrains Plugin Development Setup

This directory contains the JetBrains plugin implementation for Kilo Code, including both the IntelliJ plugin (Kotlin) and the Extension Host (Node.js/TypeScript).

Prerequisites

Before building the JetBrains plugin, ensure all dependencies are properly configured. Use the provided dependency check script to verify your setup.

Required Dependencies

1. Java Development Kit (JDK) 17

• Required Version: Java 17 (LTS)
• Why: The plugin build system requires Java 17 for compilation and runtime compatibility

• Recommended Installation (SDKMAN - works on macOS/Linux):

  # Install SDKMAN
  curl -s "https://get.sdkman.io" | bash
  source ~/.sdkman/bin/sdkman-init.sh
  
  # Install and use Java 17
  sdk install java 17.0.12-tem
  sdk use java 17.0.12-tem
  

• Alternative Installation:

  • macOS: brew install openjdk@17
  • Linux: sudo apt install openjdk-17-jdk or equivalent
  • Windows: Download from Oracle or OpenJDK

2. VSCode Submodule

• Location: deps/vscode/
• Purpose: Provides VSCode runtime dependencies and APIs for the Extension Host
• Initialization: Must be initialized before building

3. Node.js and pnpm

• Node.js: Version 20.x (as specified in package.json)
• pnpm: For workspace management and dependency installation

Quick Setup

The dependency check runs automatically as part of the build process, but you can also run it manually:

# Run dependency check manually
./jetbrains/scripts/check-dependencies.sh

# Or as part of JetBrains host build process
cd jetbrains/host && pnpm run deps:check

Note: The dependency check is automatically integrated into the Turbo build system and runs before JetBrains builds to ensure all dependencies are properly configured.

Quick Fixes for Common Issues

• "Unsupported class file major version 68": Install Java 17
• "slice is not valid mach-o file": Rebuild native modules
• "platform.zip file does not exist": Generate platform files

Manual Setup

If you prefer to set up dependencies manually:

1. Initialize VSCode Submodule

# From project root
git submodule update --init --recursive

2. Verify Java Version

java -version
# Should show Java 17.x.x

javac -version
# Should show javac 17.x.x

3. Install Node Dependencies

# From project root
pnpm install

Project Structure

jetbrains/
├── host/                    # Extension Host (Node.js/TypeScript)
│   ├── src/                # TypeScript source code
│   ├── package.json        # Node.js dependencies
│   ├── tsconfig.json       # TypeScript configuration
│   └── turbo.json          # Turbo build configuration
├── plugin/                 # IntelliJ Plugin (Kotlin/Java)
│   ├── src/main/kotlin/    # Kotlin source code
│   ├── src/main/resources/ # Plugin resources and themes
│   ├── build.gradle.kts    # Gradle build configuration
│   ├── gradle.properties   # Plugin version and platform settings
│   ├── genPlatform.gradle  # VSCode platform generation
│   └── scripts/            # Build and utility scripts
├── resources/              # Runtime resources (generated)
└── README.md              # This file

Build Modes

The plugin supports three build modes controlled by the debugMode property:

1. Development Mode (debugMode=idea)

./gradlew prepareSandbox -PdebugMode=idea

• Used for local development and debugging
• Creates .env file for Extension Host
• Copies theme resources to debug location
• Enables hot-reloading for VSCode plugin integration

2. Release Mode (debugMode=release)

./gradlew prepareSandbox -PdebugMode=release

• Used for production builds
• Requires platform.zip file (generated via genPlatform task)
• Creates fully self-contained deployment package
• Includes all runtime dependencies and node_modules

3. Lightweight Mode (debugMode=none, default)

./gradlew prepareSandbox

• Used for testing and CI
• Minimal resource preparation
• No VSCode runtime dependencies
• Suitable for static analysis and unit tests

Building the Plugin

Development Build

# From project root
pnpm jetbrains:run

# Or manually:
cd jetbrains/plugin
./gradlew runIde -PdebugMode=idea

Production Build

# Generate platform files first (if needed)
cd jetbrains/plugin
./gradlew genPlatform

# Build plugin
./gradlew buildPlugin -PdebugMode=release

Extension Host Only

# From jetbrains/host directory
pnpm build

# Or with Turbo from project root
pnpm --filter @kilo-code/jetbrains-host build

Turbo Integration

The project uses Turborepo for efficient builds and caching:

• jetbrains:bundle: Builds the complete plugin bundle
• jetbrains:run-bundle: Runs the plugin with bundle mode
• jetbrains:run: Runs the plugin in development mode

Turbo automatically handles:

• VSCode submodule initialization (deps:check)
• Dependency patching (deps:patch)
• Build caching and parallelization

Common Issues and Troubleshooting

Java Version Issues

Problem: Build fails with "Unsupported class file major version 68" or similar Java version errors Root Cause: Running Java 24+ instead of required Java 17

Solution:

Option 1: Using SDKMAN (Recommended for macOS/Linux)

# Install SDKMAN if not already installed
curl -s "https://get.sdkman.io" | bash
source ~/.sdkman/bin/sdkman-init.sh

# Install and use Java 17
sdk install java 17.0.12-tem
sdk use java 17.0.12-tem

# Make Java 17 default (optional)
sdk default java 17.0.12-tem

# Verify version
java -version  # Should show OpenJDK 17.x.x

Option 2: Using Homebrew (macOS Alternative)

# Install Java 17
brew install openjdk@17

# Set JAVA_HOME for current session
export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home

# Add to shell profile for persistence
echo 'export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home' >> ~/.zshrc

# Verify version
java -version

Option 3: Manual JAVA_HOME Setup

# Find Java 17 installation
/usr/libexec/java_home -V

# Set JAVA_HOME to Java 17 path
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

VSCode Submodule Not Initialized

Problem: Build fails with missing VSCode dependencies Solution:

# Initialize submodule
git submodule update --init --recursive

# Verify submodule is populated
ls deps/vscode/src  # Should contain VSCode source files

Missing platform.zip

Problem: Release build fails with "platform.zip file does not exist" Solution:

cd jetbrains/plugin
./gradlew genPlatform  # This will download and generate platform.zip

Node.js Version Mismatch

Problem: Extension Host build fails with Node.js compatibility errors Solution:

# Use Node.js 20.x
nvm use 20  # if using nvm
# or
node --version  # should show v20.x.x

Native Module Architecture Mismatch

Problem: Plugin fails to load with "slice is not valid mach-o file" errors for native modules like @vscode/spdlog or native-watchdog Root Cause: Native Node.js modules were compiled for wrong CPU architecture (e.g., x86_64 vs ARM64)

Solution:

# Navigate to resources directory and rebuild native modules
cd jetbrains/resources

# Clean existing modules
rm -rf node_modules package-lock.json

# Copy package.json from host
cp ../host/package.json .

# Install dependencies with npm (not pnpm to avoid workspace conflicts)
npm install

# Verify native modules are built for correct architecture
file node_modules/@vscode/spdlog/build/Release/spdlog.node
file node_modules/native-watchdog/build/Release/watchdog.node
# Should show "Mach-O 64-bit bundle arm64" on Apple Silicon or appropriate arch

# Update production dependency list
cd ../plugin
npm ls --omit=dev --all --parseable --prefix ../resources > ./prodDep.txt

# Rebuild plugin
./gradlew buildPlugin -PdebugMode=none

Prevention: When updating dependencies or switching architectures, always rebuild native modules in the jetbrains/resources/ directory.

Gradle Build Issues

Problem: Gradle tasks fail or hang Solution:

# Clean and rebuild
./gradlew clean
./gradlew build --refresh-dependencies

# Check Gradle daemon
./gradlew --stop
./gradlew build

Development Workflow

1. Initial Setup: Dependencies are automatically checked when you run any JetBrains build command
2. Development: Use pnpm jetbrains:run for live development (includes automatic dependency check)
3. Testing: Build with debugMode=none for CI/testing
4. Release: Generate platform files and build with debugMode=release

Automatic Dependency Management: The build system now automatically verifies and sets up all required dependencies (Java 17, VSCode submodule, Node.js, etc.) before each build, ensuring a smooth development experience.

Environment Variables

The plugin respects these environment variables:

• JAVA_HOME: Java installation directory
• debugMode: Build mode (idea/release/none)
• vscodePlugin: Plugin name (default: kilocode)
• vscodeVersion: VSCode version for platform generation (default: 1.100.0)

Platform Support

The plugin supports multiple platforms through the platform generation system:

• Windows: x64
• macOS: x64 and ARM64 (Apple Silicon)
• Linux: x64

Platform-specific dependencies are automatically handled during the build process.

Multi-Architecture Support: The platform generation system now includes enhanced architecture-aware native module handling, automatically creating runtime loaders that detect the current platform and load the correct native modules for each architecture.

Contributing

When making changes to the JetBrains plugin:

1. Ensure all dependencies are properly set up
2. Test in development mode first (debugMode=idea)
3. Verify builds work in all three modes
4. Update this README if adding new dependencies or requirements
5. Run the dependency check script to validate setup

Scripts

• jetbrains/scripts/check-dependencies.sh: Comprehensive dependency verification and setup
• jetbrains/plugin/scripts/sync_version.js: Version synchronization utility

For more detailed build information, see the individual package.json and build.gradle.kts files in the respective directories.