joLink

joLink Runtime

English | 简体中文

A lightweight, headless Java IDE for AI coding agents.

Closing the loop for autonomous Java development.

Design principle: Everything exists to reduce uncertainty for the LLM.

joLink does not provide an editor UI. Instead, it exposes incremental compilation, testing, application startup and breakpoint debugging through MCP to the coding agent you already use—so it can run the code, inspect real state, and verify its own changes.

Persistent compilation state and HotSwap reduce repeated full rebuilds and JVM restarts. When tests, logs and endpoint responses are not enough, the agent can use breakpoints and inspect exception events, stack frames and variables.

Free and local. It does not require a joLink account, model API key, inference provider, or separate agent application.

Install

1. Open a new chat in your coding agent.
2. Click the copy button in the code block below, paste the entire prompt into that chat, and send it.

Follow this guide:

https://github.com/L1ch404/jolink-runtime/blob/main/INSTALL.md Install joLink MCP and its English Skill for my current agent. Enable the global Java change-verification rule for this agent across projects. Use user-level installation by default and preserve existing configuration. Check the saved configuration, Skill and rule. If a client UI action or reload is needed, stop and tell me what to do; leave connection and rule-loading verification to a chat after reloading.

[!WARNING]

Following the prompt above adds a global Java verification rule to your current agent, applying across projects.

This encourages the agent to perform additional tests and runtime checks, which may increase token usage and task completion time.

If you do not want this global rule, remove the line that enables it before sending the prompt.

1. If the agent reports that a reload is needed, reconnect MCP or restart the client as instructed, then open a new chat. Configuration complete but not yet loaded is not an installation failure. In the loaded chat, you can send:

Verify the existing joLink MCP and jolink-java Skill in this client without reinstalling them.

Call the joLink status tool exposed by this client once, and check its Skill list or loading facility. If I enabled it, also check whether the global Java change-verification rule is loaded through the client's native instructions view. If anything is unavailable or its loading cannot be confirmed, report it and stop; do not write a standalone verification script. Do not start applications or run tests.

The guide provides official client-specific locations and examples for Codex, Claude Code, Cursor, VS Code/Copilot, CodeBuddy, Gemini CLI, OpenCode, Cline, Roo Code, Windsurf and Kiro. All start MCP with uvx jolink-runtime@latest and use the same English Skill; no plugin bundle or universal installer is required. MCP performs the work; the Skill explains the workflows; the optional global verification rule makes proportionate Java verification part of implementation tasks across projects. The prompt above explicitly enables it; remove that line if you only want MCP and the Skill. The guide also covers uv setup, preserving configuration, reconnection and verification.

For Chinese instructions, use the Chinese installation guide.

Why joLink

Coding agents are good at reading and changing code, but they can become stuck in a loop of static assumptions:

analyze

-> patch -> assume the patch works -> patch again

joLink adds the missing runtime feedback loop:

analyze

-> change -> run -> observe -> update the hypothesis -> change again if necessary

This is useful when:

• the Java application is not running yet;
• a code change needs to be verified against real behavior;
• repeated patches have not solved the problem;
• endpoint results do not match the source-code interpretation;
• logs or tests are insufficient to explain the executed path;
• business naming is inconsistent and static search cannot find the relevant code;
• deeper runtime evidence such as breakpoints, stacks, or variables is needed.

The goal is not to use a debugger for every problem.

Start with the cheapest useful evidence:

application status

-> logs and actual outputs -> exception events -> executed path -> breakpoints, stack frames, and variables

Debug deeper only when necessary.

What it can do

joLink exposes four focused MCP tools:

• java_application — project launch, compile-aware restart (HotSwap by default), stop, and attach;
• java_fast_test — selected Java tests, result details and cancellation, without an application launch;
• java_status — Java process discovery, compact status, on-demand details and logs;
• java_debugger — breakpoints, exception events, stacks, variables, and resume.

After editing a managed project, call java_application(action=restart). It incrementally compiles changes in the existing JDT workspace and prefers HotSwap; incompatible changes restart the JVM using those same compiled outputs. Set hotswap=false to force process/application reinitialization. The result's apply_method distinguishes HotSwap from a real restart. See restart workflow.

Fast Test uses a Maven or Gradle Probe only when its small configuration cache is absent or changed. The exported test Build World and JDT workspace persist across MCP processes. JDT keeps main and test classes current and runs explicit JUnit 4/5 or TestNG tests in an isolated JVM:

java_fast_test(action=run,

project_path=/path/to/project, source_files=[src/main/java/example/Service.java], tests=[example.ServiceTest#works], timeout=60) -> if unfinished, choose a suitable waiting interval, then call java_status(action=status) -> read diagnostics/failures with java_fast_test(action=result, test_run_id=...) -> cancel with java_fast_test(action=cancel, test_run_id=...)

java_status(status).fast_test stays compact. If compilation fails before run returns, its reply includes compiler diagnostics directly. Errors that occur after a timeout reply and failed-test details are available through result; follow the summary's next_action or use its test_run_id, without rerunning tests. Full compiler file lists are omitted. Only the active and most recently completed test attempts are retained in the current MCP session; an unavailable ID returns TEST_RUN_NOT_FOUND.

passed=false means the selected tests executed and found a failure; it is not a Tool infrastructure error. Fast Test does not require or modify a running application. The current JDT supports Java 8 through 26 source/target levels; product regression covers 8, 11, 17 and 21, including separate main/test levels. Target libraries and application/test JDKs still follow the project. Supported build layouts include Maven jar projects, one explicitly selected jar module in a standard Reactor, and Gradle Java builds including multi-Project dependencies (tested with 7.4.2, 8.10 and 8.14). Maven and Gradle multi-module launch and Fast Test resolve the selected module's upstream dependencies into separate JDT projects in one Worker. Unchanged modules reuse their output; JavaBuilder propagates changed APIs and constants to affected downstream sources. Local module dependencies use current workspace output rather than installed JARs; Maven also supports test-jar dependencies. See Gradle multi-module flow and evidence.

Demo

From an unexpected API response to runtime investigation.

Reading source code tells an agent what might happen. Running the application and inspecting its state helps the agent check what actually happens.

The screenshots below show a debugging example: an agent starts a Java application, checks an endpoint, notices an unexpected result, and uses joLink to investigate the execution path.

This is a constructed demonstration scenario, not a record of an actual business incident.

Some sensitive information in the screenshots has been redacted for privacy.

1. Start the application and check the actual response

The agent uses java_application to launch the application and java_status to check its state, then sends an HTTP request to a sample risk-scoring endpoint.

For score=80, the expected category is High Risk, but the agent reports Medium Risk. It checks additional boundary values before investigating further.

2. Set a breakpoint and inspect runtime variables

The agent uses java_debugger to set a breakpoint on the Medium Risk branch, triggers another request, and inspects the variables after the breakpoint is hit.

The conversation shows score=80 while execution is in the Medium Risk branch. This gives the agent runtime evidence to investigate its boundary-condition hypothesis, rather than relying only on source-code assumptions.

This example demonstrates application startup and runtime investigation. It is not a Fast Test performance benchmark; the screenshots cover the investigation stage, not the subsequent fix and re-verification.

Private diagnostics

joLink keeps stdout exclusively for MCP JSON-RPC. Python lifecycle logs and tracebacks are also written to a bounded private rotating file:

Windows: %LOCALAPPDATA%\jolink-runtime\logs\mcp.log

macOS/Linux: $XDG_CACHE_HOME/jolink-runtime/logs/mcp.log or ~/.cache/jolink-runtime/logs/mcp.log

status does not return mcp.log paths or logging configuration, even with details=true. Read the local file at the path above when diagnosing joLink itself. A diagnostic-file failure never prevents the MCP server from starting. The file is limited to 4 MiB with three rotated backups; stdout remains untouched.

java_status(action=status) is a compact overview: readiness, process/debug state, active operation and recent restart/Test summaries. Read java_status(action=status, details=true) for current launch errors, full last_reload, compiler/cache settings and timings. Completed launch/restart calls already return their own detailed result; the flag is useful when an operation continued after the synchronous reply timeout. Neither call reads or embeds build logs. Use java_status(action=logs, source=build) for the current launch's build log, or omit source to read application output; both accept tail. Restart summaries include a next_action pointing to details.

launch/restart replies include previous_startup_ms: the prior successful JVM startup duration saved locally for the same launch, captured before the new operation. It excludes Probe/JDT compilation. With ready_port it measures startup through observed TCP readiness; otherwise it only measures JVM/ JDWP startup. HotSwap and failed startups do not replace this observation. It is written once when startup succeeds to a small JSON file under the joLink cache's startup-timings/ directory. Stop, a new conversation or an MCP restart does not discard it. The next launch reads that file; no expiry, build-input validation or repeated status writes are involved. An unseen launch returns null. Treat it as a waiting reference, not a prediction or a readiness check.

Set JOLINK_LOG_LEVEL in the MCP server's environment and restart it: WARNING (default) keeps warnings/errors only; INFO records JDT cache/source/build/save summaries and native FULL fallback reasons; DEBUG also retains detailed W