# Interacting With Project Runtime

> Interacting with a project's JVM runtime through the Kotlin REPL to execute focused probes against project classes and dependencies. Activate when behavior must be observed by running code; use using-gradle for build inspection or task execution.

- Skill: `rnett/interacting-with-project-runtime` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rnett/interacting-with-project-runtime`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rnett/interacting-with-project-runtime/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: Apache-2.0
- Author: rnett (https://skillmd.com/u/rnett)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/rnett/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](references/repl-session-setup.md).

### Running Code

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

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

### Common Patterns

#### Probing Project Classes

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

#### Testing Coroutine Logic

```kotlin
import kotlinx.coroutines.runBlocking

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

#### Visualizing Data Structures

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

## Troubleshooting

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

## Examples

### Verify a utility function

```json
{
  "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

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