/kotlin-tooling-kotlin-toolchain

name: kotlin-tooling-kotlin-toolchain
description: >
  Load when building, running, testing, packaging, linting, or configuring a
  Kotlin/Java project with the Kotlin Toolchain (JetBrains' unified CLI, formerly
  Amper), when scaffolding a new or greenfield Kotlin project, or when the repo
  has project.yaml, module.yaml, or a ./kotlin wrapper. Skip for existing
  Gradle/Maven projects.
license: Apache-2.0
metadata:
  author: github:@singleton11
  version: "0.1.0"
  provider: anthropic
  tested_models: "anthropic/claude-sonnet-5, anthropic/claude-opus-5"
  agent_version: claude-code
  last_eval: "2026-08-14"

Kotlin Toolchain

JetBrains' unified CLI for Kotlin (JVM, Android, iOS, multiplatform) and Java projects, in Alpha. Configuration is declarative YAML instead of Gradle build scripts.

Installation

Prefer the project's checked-in wrapper: `./kotlin build` needs nothing installed — the wrapper downloads the CLI itself. Install a global CLI only when there is no wrapper (e.g. before `kotlin init`):

sdk install kotlintoolchain      # SDKMAN (macOS / Linux / WSL)

The `kotlin` command then auto-provisions its JDK on first use. Other install options (installer scripts, IntelliJ IDEA plugin) live at <https://kotlin-toolchain.org/>.

If the project root ships wrapper scripts (`kotlin` / `kotlin.bat`), the global `kotlin` detects them and proxies into them, pinning the project to the wrapper's version. Always invoke `kotlin` from the project root so the wrapper wins; never call a globally installed binary directly when a wrapper exists.

CLI commands

For the detailed list of commands and their options, run `kotlin --help` or `kotlin <command> --help`.

Project structure

project-root/
├── kotlin, kotlin.bat     # Local wrappers
├── project.yaml           # Project-level config
├── libs.versions.toml     # Version catalog (Gradle-compatible; root or gradle/)
├── module-name/
│   ├── module.yaml        # Module configuration
│   ├── src/               # Production sources (Kotlin + Java mixed when JVM platform is available)
│   ├── resources/         # Resources (copied into JAR)
│   ├── test/              # Test sources
│   └── testResources/     # Test-only resources
└── another-module/
    ├── module.yaml
    └── ...

`project.yaml` declares the project's modules and any local build plugins. See [references/examples.md](references/examples.md) for a project-level config example.

module.yaml

product: jvm/app    # jvm/app, jvm/lib, android/app, lib (multiplatform), …

dependencies:
  - org.example:artifact:1.0.0           # Maven coordinates
  - //other-module                       # Module dependency (relative path from the project root)
  - $libs.ktor.client                    # From version catalog
  - bom: io.ktor:ktor-bom:2.2.0          # BOM import
  - org.example:foo:1.0.0: exported      # Exposed to dependents (like Gradle api())
  - org.example:bar:1.0.0: compile-only
  - org.example:baz:1.0.0: runtime-only

test-dependencies:
  - io.mockk:mockk:1.13.0

settings:
  jvm:
    mainClass: org.example.MainKt   # Default: main() in main.kt
    jdk:
      version: 21
  kotlin:
    languageVersion: 2.0
  compose:
    enabled: true

test-settings:
  kotlin:
    languageVersion: 2.0

Notes:

• `module.yaml` does not support `${...}` interpolation. Values are literal strings/booleans/numbers;

paths are relative to the module root. Interpolation works only in `plugin.yaml`.

• The module name is the basename of the directory holding `module.yaml`. There is no `name:` field.
• Tests use [kotlin.test](https://kotlinlang.org/api/latest/kotlin.test/) by default, no dependency needed.

Version catalogs use the standard Gradle `libs.versions.toml` format, referenced as `$libs.<key>`. Built-in catalogs `$kotlin.*` and `$compose.*` derive their versions from `settings`.

Templates

A template extracts reusable `module.yaml` sections into a `<name>.module-template.yaml` file (same structure as `module.yaml`) that modules pull in via an `apply:` list of relative paths. It's a general reuse mechanism — sharing project-wide config is just one use. There is no enforced convention for where the file lives. Modules reference it by path under `apply:`.

Because there is no project-wide `settings:` block, templates are the only way to share configuration (Kotlin language version, common test dependencies, repositories, …) across modules. `apply:` one template everywhere for project-wide defaults, or keep several templates and apply different combinations to different subsets of modules — e.g. a common template in every module plus a service-only template in the backend modules. A module can list multiple templates under `apply:`.

# common.module-template.yaml
test-dependencies:
  - io.mockk:mockk:1.13.0
settings:
  kotlin:
    languageVersion: 2.0

# module.yaml
product: jvm/app
apply:
  - //common.module-template.yaml
  - //jvm-service.module-template.yaml

• Templates can't have `product:` or `apply:` sections — a template can't apply another template (no

recursion) and can't define products.

• Applied one by one, with `module.yaml`'s own values last: scalars are overridden, lists and mappings

appended, and `module.yaml` always wins regardless of `apply:` position.

Checks and linters

`kotlin check` runs all tests plus every registered check. Filter by name (`kotlin check detekt apiCheck`), skip with `--skip <name>` (e.g. `--skip tests`), restrict to modules with `-m <module>` (repeatable), and list what exists with `kotlin show checks`. A check fails when its underlying task throws.

The Toolchain ships no bundled linters — `tests` is the only built-in check. detekt, ktlint, and API-compatibility verification must be registered as local-plugin tasks under `checks:` in `plugin.yaml`.

Multiplatform

Platform code lives in `@platform`-suffixed directories: `src@jvm/`, `src@ios/`, `src@android/`. Common code in `src