Skip to content
This repository was archived by the owner on Feb 25, 2026. It is now read-only.

AGENTS.md

Latest commit

 

History

History
196 lines (137 loc) · 6.71 KB

AGENTS.md

File metadata and controls

196 lines (137 loc) · 6.71 KB

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 dev.
  • Local main ref may not exist; use dev or origin/dev for diffs.
  • 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
  • Typecheck: bun turbo typecheck (uses tsgo, not tsc)
  • Test: bun test from packages/opencode/ (NOT from root -- root blocks tests)
  • Single test: bun test test/tool/tool.test.ts from packages/opencode/
  • SDK regen: After changing server endpoints in packages/opencode/src/server/, run ./script/generate.ts from root to regenerate packages/sdk/js/

Monorepo Structure

Turborepo + Bun workspaces. The packages you'll work with most:

Package Name Purpose
packages/opencode/ @kilocode/cli Core CLI -- agents, tools, sessions, server, TUI. This is where most work happens.
packages/sdk/js/ @kilocode/sdk Auto-generated TypeScript SDK (client for the server API). Do not edit src/gen/ by hand.
packages/kilo-vscode/ @kilocode/kilo-vscode VS Code extension with SolidJS webview UI. See its own AGENTS.md for details.
packages/kilo-gateway/ @kilocode/kilo-gateway Kilo auth, provider routing, API integration
packages/kilo-telemetry/ @kilocode/kilo-telemetry PostHog analytics + OpenTelemetry
packages/kilo-i18n/ @kilocode/kilo-i18n Internationalization / translations
packages/app/ @opencode-ai/app Web/TUI frontend (SolidJS + Vite)
packages/util/ @opencode-ai/util Shared utilities (error, path, retry, slug, etc.)
packages/plugin/ @kilocode/plugin Plugin/tool interface definitions

Other packages (desktop/, containers/, extensions/) are for desktop app, Docker containers, and editor extensions.

Style Guide

  • Keep things in one function unless composable or reusable
  • Avoid unnecessary destructuring. Instead of const { a, b } = obj, use obj.a and obj.b to preserve context
  • Avoid try/catch where possible
  • Avoid using the any type
  • Prefer single word variable names where possible
  • Use Bun APIs when possible, like Bun.file()
  • Rely on type inference when possible; avoid explicit type annotations or interfaces unless necessary for exports or clarity

Avoid let statements

We don't like let statements, especially combined with if/else statements. Prefer const.

Good:

const foo = condition ? 1 : 2

Bad:

let foo

if (condition) foo = 1
else foo = 2

Avoid else statements

Prefer early returns or using an iife to avoid else statements.

Good:

function foo() {
  if (condition) return 1
  return 2
}

Bad:

function foo() {
  if (condition) return 1
  else return 2
}

No empty catch blocks

Never leave a catch block empty. An empty catch silently swallows errors and hides bugs. If you're tempted to write one, ask yourself:

  1. Is the try/catch even needed? (prefer removing it)
  2. Should the error be handled explicitly? (recover, retry, rethrow)
  3. At minimum, log it so failures are visible

Good:

try {
  await save(data)
} catch (err) {
  log.error("save failed", { err })
}

Bad:

try {
  await save(data)
} catch {}

Prefer single word naming

Try your best to find a single word name for your variables, functions, etc. Only use multiple words if you cannot.

Good:

const foo = 1
const bar = 2
const baz = 3

Bad:

const fooBar = 1
const barBaz = 2
const bazFoo = 3

Testing

You MUST avoid using mocks as much as possible. Tests MUST test actual implementation, do not duplicate logic into a test.

Fork Merge Process

Kilo CLI is a fork of opencode.

Minimizing Merge Conflicts

We regularly merge upstream changes from opencode. To minimize merge conflicts and keep the sync process smooth:

  1. Prefer kilocode directories - Place Kilo-specific code in dedicated directories whenever possible:

    • packages/opencode/src/kilocode/ - Kilo-specific source code
    • packages/opencode/test/kilocode/ - Kilo-specific tests
    • packages/kilo-gateway/ - The Kilo Gateway package

  2. Minimize changes to shared files - When you must modify files that exist in upstream opencode, keep changes as small and isolated as possible.

  3. Use kilocode_change markers - When modifying shared code, mark your changes with kilocode_change comments so they can be easily identified during merges. Do not use these markers in files within directories with kilo in the name

  4. Avoid restructuring upstream code - Don't refactor or reorganize code that comes from opencode unless absolutely necessary.

The goal is to keep our diff from upstream as small as possible, making regular merges straightforward and reducing the risk of conflicts.

Kilocode Change Markers

To minimize merge conflicts when syncing with upstream, mark Kilo Code-specific changes in shared code with kilocode_change comments.

Single line:

const value = 42 // kilocode_change

Multi-line:

// kilocode_change start
const foo = 1
const bar = 2
// kilocode_change end

New files:

// kilocode_change - new file

When markers are NOT needed

Code in these paths is Kilo Code-specific and does NOT need kilocode_change markers:

  • packages/opencode/src/kilocode/ - All files in this directory
  • packages/opencode/test/kilocode/ - All test files for kilocode
  • Any other path containing kilocode in filename or directory name

These paths are entirely Kilo Code additions and won't conflict with upstream.