kilocode AGENTS.md

AGENTS.md

Kilo CLI is an open source AI coding agent that generates code from natural language, automates tasks, and supports 500+ AI models.

• ALWAYS USE PARALLEL TOOLS WHEN APPLICABLE.
• The default branch in this repo is main.
• Prefer automation: execute requested actions without confirmation unless blocked by missing info or safety/irreversibility.
• You may be running in a git worktree. All changes must be made in your current working directory — never modify files in the main repo checkout.

Build and Dev

• Dev: bun run dev (runs from root) or bun run --cwd packages/opencode --conditions=browser src/index.ts
• Dev with params: bun dev -- help
• Extension: bun run extension (build + launch VS Code with the extension in dev mode). Pass --no-build to skip the build. When asked to run an isolated VS Code/Kilo environment, use the CLI scripts instead of interactive launch configs: bun run extension:isolated reuses .kilo-dev/, and bun run extension:isolated:clean clears .kilo-dev/ first. Pass an optional workspace path after --, for example bun run extension:isolated -- ../sample-project.
• Typecheck: bun turbo typecheck (uses tsgo, not tsc). Includes the JetBrains plugin and requires Java 21; do not run java -version as a routine preflight. Only check Java when a Gradle/Java command fails with a Java-version or missing-Java error. If missing, install via SDKMAN: sdk install java 21-tem && sdk use java 21-tem. If SDKMAN is not installed, see https://sdkman.io/install.
• Test: bun test from packages/opencode/ (NOT from root -- root blocks tests)
• Single test: bun test ./test/tool/tool-define.test.ts from packages/opencode/
• CLI build artifact size check: after bun run script/build.ts --single --skip-install in packages/opencode/, use du -h dist/*/*/bin/kilo (scoped package output lives under dist/@kilocode/)
• SDK regen: After changing server endpoints in packages/opencode/src/server/, run ./script/generate.ts from root to regenerate packages/sdk/js/
• Knip (unused exports): bun run knip from packages/kilo-vscode/. CI runs this — all exported types/functions must be imported somewhere. Remove or unexport unused exports before pushing.
• Source links: After adding or changing 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 and commit the updated packages/kilo-docs/source-links.md. CI runs this check — the build fails if the file is stale.
• kilocode_change check: bun run check-kilocode-change from packages/kilo-vscode/. CI runs this — kilocode_change is a marker for upstream merge conflicts and must not appear in packages/kilo-vscode/ or packages/kilo-ui/ (these are entirely Kilo Code additions). Remove the markers before pushing.
• opencode annotation check: bun run script/check-opencode-annotations.ts --worktree from repo root when verifying local agent changes. CI runs bun run script/check-opencode-annotations.ts on PRs touching packages/opencode/ — every Kilo-specific change in shared opencode files must be annotated with kilocode_change markers. Exempt paths (no markers needed): packages/opencode/src/kilocode/, packages/opencode/test/kilocode/, and any path containing kilocode in the name.
• Effect facade ratchet: Do not add runtime-backed Promise facades to shared packages/opencode/src Effect services; use service dependencies, AppRuntime, or Kilo-owned boundaries. Run bun run script/check-opencode-promise-facades.ts when touching service adapters.
• workflow allowlist: bun run script/check-workflows.ts from repo root. CI runs this as part of the annotations workflow — any .yml / .yaml file added to or removed from .github/workflows/ must be reflected in the hardcoded list in script/check-workflows.ts. Prevents upstream-merged workflows from silently starting to run in our CI.
• Backend/SDK programmatic testing: see TESTING.md for spawning the local main-branch backend (bun dev serve) and driving it via curl — use this instead of kilo serve (prod binary) when testing backend fixes.