Help us improve
Share bugs, ideas, or general feedback.
Provides safety rules, workflows, and tool reference for debugging Java applications via IntelliJ debugger: breakpoints, stepping, expression evaluation, and runtime state inspection.
npx claudepluginhub amplicode/spring-skills --plugin spring-toolsHow this skill is triggered — by the user, by Claude, or both
Slash command
/amplicode-spring-skills:java-debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill is part of the **Spring Agent Toolkit** and is designed to work with the **IntelliJ Debug MCP server** (provided by the Amplicode IntelliJ plugin alongside the main Amplicode MCP). Before doing anything else, check your tool list for any debug MCP tool — they are exposed under the `intellij-debug` MCP server (e.g. `toggle_breakpoint`, `evaluate_expression`, `get_stack_trace`); harnes...
Debugs Java applications using JDB CLI: attach to running JVMs with JDWP, launch new ones under debugger, set breakpoints, step code, inspect variables/threads, diagnose exceptions.
Debug live Java applications via JDWP with breakpoints, state inspection, expression evaluation, variable mutation, logpoints, and field watchpoints.
Debugs crashing programs, failing tests, or incorrect code outputs by pausing at breakpoints to inspect runtime state, variables, types, call stacks. Attaches to running servers by PID without restarts.
Share bugs, ideas, or general feedback.
This skill is part of the Spring Agent Toolkit and is designed to work with the IntelliJ Debug MCP server (provided by the Amplicode IntelliJ plugin alongside the main Amplicode MCP). Before doing anything else, check your tool list for any debug MCP tool — they are exposed under the intellij-debug MCP server (e.g. toggle_breakpoint, evaluate_expression, get_stack_trace); harnesses that flatten MCP tools into the tool list use the mcp__intellij-debug__ prefix on the same names.
amplicode-install skill (bundled with the Spring Agent Toolkit). It installs the Amplicode plugin and walks the user through the «Настроить Spring Agent» welcome-screen button + MCP-client restart. After it completes, the debug MCP tools become available — resume this skill.amplicode-install is not registered in your skill list, tell the user (in their language): "This skill needs the Amplicode IntelliJ plugin and its debug MCP server. Install it from https://amplicode.ru/marketplace into IntelliJ IDEA Ultimate/Community or GigaIDE, open any project, click «Настроить Spring Agent» on the Amplicode welcome screen, then restart your MCP client."This skill guides you through debugging applications via the IntelliJ Debug MCP server. The MCP server runs inside IntelliJ IDEA and gives you programmatic control over the debugger.
These rules prevent you from hanging indefinitely or losing debugging context. They exist because the debugged application can be suspended on a breakpoint at any time, which means it stops responding to all requests.
When the app hits a breakpoint, its threads freeze. Any HTTP request, curl call, or network interaction you make to that app will hang forever — the app can't respond until you resume it. This is the single most common mistake.
Rule 1: Always use timeouts when talking to the debugged app.
Use --max-time 5 with curl, or set run_in_background: true on Bash tool calls. Do this even if you just checked that the app is running — it could hit a breakpoint between your check and your request.
Rule 2: Check suspension status before network calls.
Call list_debug_sessions and look at isSuspended. If the app is suspended, either resume it first or accept your request will block.
Rule 3: Always verify position after stepping.
After step_over, step_into, or step_out, call get_current_position. Never assume where execution landed — it might have jumped to an unexpected line or even a different file.
Rule 4: Check status after resume.
After calling resume, the app may immediately hit another breakpoint. Always call list_debug_sessions or get_current_position to confirm whether the session is still running or suspended again.
Rule 5: Expression evaluation has side effects.
evaluate_expression runs real code in the debugged JVM. Avoid expressions that modify state (like setters or System.exit(0)) unless that's specifically what you intend.
Before using any debug tool, initialize the session:
initialize with projectPath set to the absolute path of the project root| Tool | Parameters |
|---|---|
initialize | projectPath (string, required) — absolute path to project root |
| Tool | Parameters |
|---|---|
list_run_configurations | (none) |
debug_run_configuration | configurationName (string, required) — exact name of the run config |
list_debug_sessions | (none) — returns session names and isSuspended status |
stop_debug_session | sessionName (string, required) |
| Tool | Parameters |
|---|---|
list_breakpoints | (none) |
add_breakpoint | filePath (string, required), line (int, required, 1-based), condition (string, optional) |
remove_breakpoint | filePath (string, required), line (int, required, 1-based) |
toggle_breakpoint | filePath (string, required), line (int, required, 1-based), enabled (bool, optional — toggles if omitted) |
set_breakpoint_condition | filePath (string, required), line (int, required, 1-based), condition (string, required — empty string removes) |
| Tool | Parameters |
|---|---|
resume | sessionName (string, optional — defaults to first active session) |
pause | sessionName (string, optional) |
step_over | sessionName (string, optional) |
step_into | sessionName (string, optional) |
step_out | sessionName (string, optional) |
| Tool | Parameters |
|---|---|
get_current_position | sessionName (string, optional) — returns file, line, isSuspended |
get_stack_trace | sessionName (string, optional) — returns frames with file, line, description |
list_threads | sessionName (string, optional) — returns thread names and top frame info |
evaluate_expression | expression (string, required), sessionName (string, optional), frameIndex (int, optional, 0-based, default 0) |
Note: All line numbers in breakpoint tools are 1-based (matching what you see in source files). Use absolute file paths or paths relative to the project root.
Use this when you know roughly where the bug is (a specific file/method/line).
add_breakpoint at the line you want to inspect (use condition if you only care about specific cases)debug_run_configuration to start the app in debug mode--max-time 5 with curl or run_in_background: trueget_current_position — confirm the breakpoint was hit and you're at the expected lineevaluate_expression — inspect variables, call methods, check state. Start simple (variable names), then build up to more complex expressionsget_stack_trace — understand how execution reached this pointstep_over/step_into to trace further, add_breakpoint elsewhere, or concludeget_current_position to confirm where you areresume or stop_debug_session, then remove_breakpoint to clean upUse this when you need to understand how unfamiliar code actually executes.
list_run_configurations — find the right way to start the appdebug_run_configuration to start debuggingget_stack_trace to see the full call chainstep_into to follow execution into methods, step_over to skip known code, step_out to return to callersevaluate_expression liberally — inspect method arguments, return values, object fieldsget_current_position to stay orientedframeIndex lets you evaluate in different stack frames: 0 = current (top) frame, 1 = caller, etc.| Error | What it means | What to do |
|---|---|---|
| "Session not found" | No session with that name, or no sessions running | list_debug_sessions to see what's available. May need to start a new one. |
| "Not suspended" | Session is running, not paused on a breakpoint | The breakpoint wasn't hit yet, or was already resumed. Wait for the trigger, or pause the session. |
| "Evaluator not available" | The current frame doesn't support evaluation | Try a different frameIndex. Native or framework frames often can't evaluate. |
| Session crash/disconnect | The debugged app crashed or was killed | Check IDE logs. list_debug_sessions to confirm. Start a new debug session. |
After debugging is complete, clean up: remove_breakpoint for any breakpoints you added. Leaving breakpoints behind clutters future debug sessions.
When more than one debug session is active, always specify sessionName in your tool calls — otherwise the tools default to the first active session, which may not be the one you intend.
Call list_debug_sessions to discover all active sessions and their states before operating.
evaluate_expression to check state, or ask the user what they see in the IDE console.resume, an HTTP request, or debug_run_configuration), check status with list_debug_sessions or get_current_position. Don't use timed polling — just check after each relevant action.