OpenParable
Skip to content
← Back to skills

Interacting With Project Runtime

Testing & Quality
interacting_with_project_runtime

Interacting With Project Runtime is an Agent Skill for testing & quality published in the Kotlin/kotlinx-rpc repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Provides a persistent, project-aware Kotlin REPL for rapid logic verification and prototyping within the project's JVM classpath; use for testing dynamic behavior, prototyping snippets, or rendering Compose UI previews. Do NOT use for exploring library APIs (prefer `searching_dependency_sources`) or running Gradle builds.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Kotlin/kotlinx-rpc/blob/HEAD/.claude/skills/interacting_with_project_runtime/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/interacting-with-project-runtime, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Authoritative Project Runtime & Source Interaction

Probes project logic, tests utility functions, and interacts with the JVM runtime of your source sets with absolute precision using a project-aware REPL.

Constitution

  • ALWAYS prefer reading source code via search_dependency_sources and read_dependency_sources for exploring unfamiliar library APIs.
  • ALWAYS use kotlin_repl instead of a standalone Kotlin REPL for project-aware interaction.
  • ALWAYS provide absolute paths for projectRoot.
  • ALWAYS start a REPL session with the correct projectPath and sourceSet (e.g., main, test).
  • ALWAYS restart the REPL (stop then start) after modifying project source code to pick up changes in the classpath.
  • ALWAYS use the responder API for rich output (images, markdown) to improve diagnostic visibility.
  • NEVER leave a REPL session running indefinitely; use stop when finished.

Directives

  • Read the source first: For exploring unfamiliar library APIs or internal project utilities, ALWAYS prefer reading the source code first. It provides complete context, implementation details, and documentation that a REPL cannot easily expose. Use search_dependency_sources to find definitions and read_dependency_sources to analyze them.
  • ALWAYS use project-aware REPL: Only the kotlin_repl tool provides full access to the project's exact classpath, dependencies, and source sets. NEVER attempt to use standalone runners for project-internal logic.
  • Identify the environment: When starting a session, ALWAYS ensure you select the appropriate projectPath (e.g., :app) and sourceSet (e.g., main for application code, test for test utility access).
  • Pick up source changes: The REPL uses a static snapshot of the classpath. If you change project code, you MUST stop and then start the session again to pick up the updated classes.
  • Utilize the responder: ALWAYS use responder.render(value) or specialized methods (markdown, image, html) to return rich content.
  • Import necessary classes: ALWAYS provide explicit imports for project-specific and library classes.
  • Use envSource: SHELL if environment variables are missing: If the REPL fails to find expected environment variables (e.g., JAVA_HOME or specific JDKs), it may be because the host process started before the shell environment was fully loaded. Set env: { envSource: "SHELL" } when calling start to force a new shell process to query the environment.
  • Resolve {baseDir} manually: If your environment does not automatically resolve the {baseDir} placeholder in reference links, treat it as the absolute path to the directory containing this SKILL.md file.

When to Use

  • Rapid Logic Verification: When you need to quickly test a function, algorithm, or class behavior without the overhead of writing a full test suite.
  • Interactive Prototyping: When you want to experiment with a snippet of logic within the exact context of your project's dependencies and JVM configuration before implementing it.
  • Visual Component Auditing: When iterating on UI components (e.g., Compose) and you need to see the result instantly by rendering them to images.
  • Dynamic State & Data Probing: When you need to perform one-off data transformations or queries using your project's existing utility classes.

Workflows

Starting an Authoritative Session

  1. Identify the project module (e.g., :app) and source set (e.g., main).
  2. Call kotlin_repl(command="start").
  3. Optionally provide env for environment variables or additionalDependencies if you need external libraries not currently in the project.

Probing Code & State

  1. Use kotlin_repl(command="run") with your Kotlin code.
  2. Use responder.render() for rich diagnostics.
  3. Review the returned text or image content.

Lifecycle Management

  1. Use kotlin_repl(command="stop") once your investigation is complete to release system resources.

Examples

Probing a project utility function

// Start the session
{
  "command": "start",
  "projectPath": ":my-project",
  "sourceSet": "main"
}

// Execute the probe
{
  "command": "run",
  "code": "import com.example.utils.MyHelper\nMyHelper.calculateSum(1, 2)"
}
// Reasoning: Using kotlin_repl to verify a utility function in the context of the main source set.

Visualizing a UI Component

import androidx.compose.ui.test.*
import com.example.ui.MyComposable

runComposeUiTest {
    setContent { MyComposable() }
    val bitmap = onRoot().captureToImage()
    responder.render(bitmap)
}
// Reasoning: Using the responder API to retrieve a high-resolution image of a Compose component.

Troubleshooting

  • REPL Not Started: You must call start successfully before calling run.
  • ClassNotFoundException: Ensure the project has been built at least once and that you have selected the correct sourceSet (e.g., test if the class is in src/test/kotlin).
  • Changes Not Reflected: If your code changes aren't appearing, stop and start the REPL to refresh the classpath.