Gradle-mcp interacting_with_project_runtime

install

source · Clone the upstream repo

git clone https://github.com/rnett/gradle-mcp

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/rnett/gradle-mcp "$T" && mkdir -p ~/.claude/skills && cp -r "$T/src/main/skills/interacting_with_project_runtime" ~/.claude/skills/rnett-gradle-mcp-interacting-with-project-runtime && rm -rf "$T"

manifest: src/main/skills/interacting_with_project_runtime/SKILL.md

source content

Authoritative Project Runtime Interaction

Runs Kotlin code interactively within the project's exact JVM classpath — for when you need to execute, not just read.

Constitution

The core decision rule: If the question is "what does this API look like or how does it work?" → use
```
search_dependency_sources
```
/
```
read_dependency_sources
```
(read the source). If the question is "what happens when I run this?" → use
```
kotlin_repl
```
.
NEVER start a REPL session to learn about an API. Reading indexed sources is instantaneous, shows the full implementation with all overloads, and requires no JVM process.
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.
REPL Session Management: Explicitly terminate previous REPL sessions in
```
ReplTools
```
before starting new ones when session IDs are regenerated. This prevents leaking worker processes and ensures stable session management during concurrent or sequential tool calls.

Directives

Read to understand, run to verify: If you need to understand what an API does — its signature, parameters, overloads, or implementation — read its source via
```
search_dependency_sources
```
/
```
read_dependency_sources
```
. Only reach for the REPL once you know what you want to call and need to observe actual runtime output.
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()
```
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 (you need to RUN code)

Behavior Verification: You know the API, you've written the call, and you need to observe the actual runtime output or side-effects.
Logic Prototyping: Experimenting with an algorithm or snippet of your own code before committing it to source.
Visual Component Auditing: Rendering Compose UI components to images for visual review.
Dynamic Data Probing: One-off data transformations using your project's existing utilities where the output depends on runtime state.

When NOT to Use (you need to READ source instead)

Ask yourself: "Am I trying to understand this API, or run it?"

If you're trying to understand it — what methods it has, what its parameters are, how it's implemented — stop and use

searching_dependency_sources

first. The REPL cannot tell you what you don't already know to ask; source reading can. Examples of what belongs in source reading, not the REPL:

"What methods does
```
SomeClass
```
have?" →
```
search_dependency_sources
```
DECLARATION search
"What does this function do internally?" →
```
read_dependency_sources
```
"What are the parameters / overloads of this function?" →
```
read_dependency_sources
```
"Does this library have a class for X?" →
```
search_dependency_sources
```
FULL_TEXT or DECLARATION search

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
```
env
```
for environment variables or
```
additionalDependencies
```
if 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
```
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.