editor/protocol.md

TCP Protocol

Transport: UTF-8 JSON objects separated by \n.

File paths in text and intelligence requests are normalized to absolute daemon-side paths before being used as document keys.

Request

{"id":1,"method":"workspace/open","params":{"root":"/home/me/project"}}

Response

{"id":1,"ok":true,"result":{"root":"/home/me/project","gradle":true,"modules":[],"sourceRoots":[],"tasks":[]}}

Error

{"id":1,"ok":false,"error":{"code":"UNKNOWN_METHOD","message":"No handler for method"}}

Event

{"event":"workspace/indexing","params":{"state":"started"}}

Diagnostics are also published asynchronously after text/open and text/change:

{"event":"diagnostics/publish","params":{"path":"/home/me/project/src/main/kotlin/App.kt","version":7,"diagnostics":[]}}

Current Methods

The kotlin/* names are historical protocol names. Diagnostics and heuristic intelligence currently also handle .java files where noted.

• ping
• workspace/open
• workspace/close
• text/open
• text/change
• text/close
• kotlin/diagnostics
• kotlin/completion
• kotlin/definition
• kotlin/references
• kotlin/rename
• kotlin/hover
• gradle/tasks
• gradle/run

workspace/open Result

Module sourceRoots and testSourceRoots include Gradle IdeaModel roots plus common generated Kotlin/Java source directories under build/generated/ when those directories already exist.

{
  "root": "/home/me/project",
  "gradle": true,
  "modules": [
    {
      "name": "app",
      "gradlePath": ":app",
      "directory": "/home/me/project/app",
      "sourceRoots": [],
      "testSourceRoots": [],
      "resourceRoots": [],
      "testResourceRoots": []
    }
  ],
  "sourceRoots": [],
  "tasks": []
}

gradle/run Request

{"id":2,"method":"gradle/run","params":{"task":":app:test"}}

kotlin/diagnostics Request

Supports Kotlin and Java files. Kotlin diagnostics use the embedded Kotlin compiler; Java diagnostics use the JDK compiler. Main files use main source roots, while test files use main plus test source roots. Existing module output directories under build/classes/ and build/resources/ are added to the compiler classpath.

{"id":3,"method":"kotlin/diagnostics","params":{"path":"/home/me/project/src/main/kotlin/App.kt"}}

kotlin/diagnostics Result

{
  "diagnostics": [
    {
      "severity": "error",
      "message": "Syntax error",
      "path": "/home/me/project/src/main/kotlin/App.kt",
      "line": 1,
      "column": 12
    }
  ]
}

kotlin/completion Request

Returns prefix-filtered Kotlin/Java keywords plus heuristic declarations and identifiers from the current buffer and workspace.

{"id":4,"method":"kotlin/completion","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8}}

line and column are 1-based.

kotlin/completion Result

{
  "items": [
    {"label": "fun", "kind": "keyword"}
  ]
}

kotlin/hover Request

Returns keyword or heuristic Kotlin/Java declaration information for the identifier at the requested position.

{"id":5,"method":"kotlin/hover","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8}}

line and column are 1-based.

kotlin/hover Result

{"contents":"Kotlin keyword `fun`"}

contents is null when no hover information is available.

kotlin/definition Request

Returns heuristic Kotlin/Java declaration locations for the identifier at the requested position.

{"id":6,"method":"kotlin/definition","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8}}

line and column are 1-based.

kotlin/definition Result

{
  "locations": [
    {"path": "/home/me/project/src/main/kotlin/App.kt", "line": 4, "column": 7}
  ]
}

kotlin/references Request

Returns heuristic Kotlin/Java text references for the identifier at the requested position.

{"id":7,"method":"kotlin/references","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8}}

line and column are 1-based.

kotlin/references Result

{
  "locations": [
    {"path": "/home/me/project/src/main/kotlin/App.kt", "line": 4, "column": 7}
  ]
}

kotlin/rename Request

{"id":8,"method":"kotlin/rename","params":{"path":"/home/me/project/src/main/kotlin/App.kt","line":10,"column":8,"newName":"newSymbol"}}

This is currently preview-only. It does not modify files. newName must be a valid identifier and must not be a Kotlin or Java keyword.

kotlin/rename Result

{
  "applied": false,
  "oldName": "oldSymbol",
  "newName": "newSymbol",
  "edits": [
    {"path": "/home/me/project/src/main/kotlin/App.kt", "line": 4, "column": 7, "oldText": "oldSymbol", "newText": "newSymbol"}
  ]
}