interacting-with-project-runtime

Persistent JVM/Kotlin REPL for Project Runtime Probing

Executes Kotlin code interactively within the project's full runtime classpath, enabling rapid logic verification and state inspection without a full build cycle.

Positive Triggers (when to activate)

• Verifying dynamic behavior of a class or function in the project runtime.
• Probing internal state or executing experimental logic without a full build cycle.
• Rapidly prototyping logic changes within the JVM classpath.

Negative Triggers (when NOT to activate)

• Operating a Gradle build (use using-gradle).
• Modifying build definitions (use authoring-gradle-builds).
• Rendering Compose UI components (use verifying-compose-ui).

Constitution

• ALWAYS prefer reading source code over running it when the question is about API shape, signatures, or static behavior.
• Use the REPL when you need to verify runtime behavior: dynamic dispatch, state mutations, side effects, or complex logic that is hard to reason about statically.
• ALWAYS call stop after finishing a session to release JVM resources.
• NEVER run code that modifies project files, deletes data, or has irreversible side effects without explicit user approval.
• After modifying project source code, call stop then start to pick up classpath changes.

Directives

Starting a Session

Call kotlin_repl(command="start", projectPath=":module", sourceSet="main") to initialize a REPL session. The session runs in a dedicated worker process with the project's full classpath.

For session parameters, lifecycle management, and environment troubleshooting, see REPL Session Setup.

Running Code

Call kotlin_repl(command="run", code="...") to execute a Kotlin snippet. Session state (variables, imports, class definitions) persists between calls.

// Example: Verify a utility function
val result = MyUtils.parseDate("2024-01-15")
println("Parsed: $result, type: ${result::class.simpleName}")

Common Patterns

Probing Project Classes

// Inspect a service's behavior
val service = MyService()
val output = service.process("test-input")
println("Output: $output")
println("State: ${service.internalState}")

Testing Coroutine Logic

import kotlinx.coroutines.runBlocking

runBlocking {
    val result = mySuspendFunction()
    println("Result: $result")
}

Visualizing Data Structures

val tree = buildTree(sampleData)
println(tree.toPrettyString())

Troubleshooting

For session startup, classpath, and environment issues, see REPL Session Setup. If a slow session start traces back to a slow build, or a test you are probing is intermittently failing, a published Build Scan (via Develocity) can provide evidence of where the time or flakiness originates; for a test that keeps flaking across runs, Flaky Tests Detection and Failure Analytics distinguish flaky behavior from a real regression. Develocity publishes an llms.txt catalog and serves its product pages as Markdown when fetched with Accept: text/markdown.

Examples

Verify a utility function

{
  "command": "start",
  "projectPath": ":app",
  "sourceSet": "main"
}
// Then:
{
  "command": "run",
  "code": "val result = StringUtils.slugify(\"Hello World!\"); println(result)"
}
// Then:
{
  "command": "stop"
}

Prototype logic with test dependencies

{
  "command": "start",
  "projectPath": ":",
  "sourceSet": "test",
  "additionalDependencies": ["org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0"]
}