Interacting With Project Runtime
Testing & Qualityinteracting_with_project_runtimeInteracting 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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_sourcesandread_dependency_sourcesfor exploring unfamiliar library APIs. - ALWAYS use
kotlin_replinstead of a standalone Kotlin REPL for project-aware interaction. - ALWAYS provide absolute paths for
projectRoot. - ALWAYS start a REPL session with the correct
projectPathandsourceSet(e.g.,main,test). - ALWAYS restart the REPL (
stopthenstart) after modifying project source code to pick up changes in the classpath. - ALWAYS use the
responderAPI for rich output (images, markdown) to improve diagnostic visibility. - NEVER leave a REPL session running indefinitely; use
stopwhen 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_sourcesto find definitions andread_dependency_sourcesto analyze them. - ALWAYS use project-aware REPL: Only the
kotlin_repltool 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) andsourceSet(e.g.,mainfor application code,testfor test utility access). - Pick up source changes: The REPL uses a static snapshot of the classpath. If you change project code, you MUST
stopand thenstartthe session again to pick up the updated classes. - Utilize the
responder: ALWAYS useresponder.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: SHELLif environment variables are missing: If the REPL fails to find expected environment variables (e.g.,JAVA_HOMEor specific JDKs), it may be because the host process started before the shell environment was fully loaded. Setenv: { envSource: "SHELL" }when callingstartto 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 thisSKILL.mdfile.
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
- Identify the project module (e.g.,
:app) and source set (e.g.,main). - Call
kotlin_repl(command="start"). - Optionally provide
envfor environment variables oradditionalDependenciesif you need external libraries not currently in the project.
Probing Code & State
- Use
kotlin_repl(command="run")with your Kotlin code. - Use
responder.render()for rich diagnostics. - Review the returned text or image content.
Lifecycle Management
- 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
startsuccessfully before callingrun. - ClassNotFoundException: Ensure the project has been built at least once and that you have selected the correct
sourceSet(e.g.,testif the class is insrc/test/kotlin). - Changes Not Reflected: If your code changes aren't appearing,
stopandstartthe REPL to refresh the classpath.