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}")