Skip to content

Commit b06021e

Browse files
wenytang-mswenytang-ms
authored
feat: custom debug java agent (#1593)
* feat: mcp toool * feat: add agent.md * feat: debug agent design * feat: update debug logic * feat: debug agent design * ci: update * docs: update the clean up logic * docs: update * feat: update * docs: readme * fix: fix tslint error * fix: update code * fix: update * feat: update * fix: fix lint
1 parent 89ec914 commit b06021e

File tree

11 files changed

+2936
-16
lines changed

11 files changed

+2936
-16
lines changed

‎README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ A lightweight Java Debugger based on [Java Debug Server](https://github.com/Micr
1717
- Debug console
1818
- Evaluation
1919
- Hot Code Replace
20+
- No-Config Debug (debug Java apps without launch.json)
21+
- **[AI]** AI-Assisted Debugging (GitHub Copilot integration)
2022

2123
## Requirements
2224
- JDK (version 1.8.0 or later)
@@ -41,6 +43,38 @@ ext install vscode-java-debug
4143

4244
Please also check the documentation of [Language Support for Java by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) if you have trouble setting up your project.
4345

46+
## No-Config Debug
47+
48+
You can now debug Java applications without creating a `launch.json` file! Simply open a terminal in VS Code and use the `debugjava` command:
49+
50+
```bash
51+
# Debug a main class
52+
debugjava -cp bin com.example.Main
53+
54+
# Debug a JAR file
55+
debugjava -jar target/myapp.jar
56+
57+
# Debug with arguments
58+
debugjava -cp bin com.example.Main arg1 arg2
59+
```
60+
61+
The debugger will automatically attach. See [No-Config Debug Documentation](bundled/scripts/noConfigScripts/README.md) for more details.
62+
63+
## AI-Assisted Debugging
64+
65+
When using GitHub Copilot Chat, you can now ask AI to help you debug Java applications! The extension provides a Language Model Tool that enables natural language debugging:
66+
67+
- "Debug my Spring Boot application"
68+
- "Debug the Main class in this project"
69+
- "Debug Calculator with arguments 10 and 5"
70+
71+
The AI will automatically:
72+
1. Detect your project type (Maven/Gradle/VS Code)
73+
2. Build/compile your project
74+
3. Start debugging with appropriate configuration
75+
76+
See [Language Model Tool Documentation](bundled/agents/README.md) for more details.
77+
4478
## Options
4579

4680
### Launch

‎bundled/agents/README.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Java Debug Agent
2+
3+
The Java Debug Agent is an AI-powered debugging assistant that integrates with GitHub Copilot Chat to help you debug Java applications using natural language.
4+
5+
## Overview
6+
7+
Instead of manually setting breakpoints and inspecting variables, you can simply describe your debugging task in natural language. The agent will:
8+
9+
1. Analyze your code to form hypotheses
10+
2. Set targeted breakpoints
11+
3. Inspect variables and evaluate expressions
12+
4. Find the root cause of bugs
13+
14+
## Requirements
15+
16+
- VS Code 1.95.0 or later
17+
- [Language Support for Java by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java)
18+
- [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug)
19+
- GitHub Copilot Chat extension
20+
21+
## Getting Started
22+
23+
### 1. Open Copilot Chat
24+
25+
Press `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Shift+I` (macOS) to open Copilot Chat.
26+
27+
### 2. Switch to JavaDebug Agent Mode
28+
29+
In the Copilot Chat panel, click on the agent selector (usually shows "Copilot" or current agent name) and select **JavaDebug** from the dropdown list.
30+
31+
![Select Agent](images/javadebug.png)
32+
<!-- TODO: Add screenshot showing agent selector dropdown -->
33+
34+
### 3. Enter Your Debugging Request
35+
36+
Once in JavaDebug mode, simply type your debugging request:
37+
38+
```
39+
Why am I getting a NullPointerException in OrderService?
40+
```
41+
42+
![Invoke Agent](images/invoke-agent.png)
43+
<!-- TODO: Add screenshot showing chat input -->
44+
45+
### 4. Let the Agent Work
46+
47+
The agent will:
48+
- Read relevant code files
49+
- Form a hypothesis about the bug
50+
- Set breakpoints at strategic locations
51+
- Start or attach to a debug session
52+
- Inspect variables to verify the hypothesis
53+
- Report the root cause
54+
55+
![Agent Working](images/agent-working.png)
56+
<!-- TODO: Add screenshot showing agent analyzing code -->
57+
58+
## Example Usage
59+
60+
### Debug a NullPointerException
61+
62+
```
63+
I'm getting NPE when calling userService.getUser()
64+
```
65+
66+
The agent will:
67+
1. Read `UserService.java`
68+
2. Hypothesize which variable might be null
69+
3. Set a breakpoint before the NPE
70+
4. Check variable values
71+
5. Report: "The `user` variable is null because `findById()` returns null when ID doesn't exist"
72+
73+
### Debug Wrong Calculation Result
74+
75+
```
76+
The calculateTotal() method returns wrong value
77+
```
78+
79+
### Debug with Specific Input
80+
81+
```
82+
Debug processOrder with orderId=456
83+
```
84+
85+
### Debug Multi-threaded Issues
86+
87+
```
88+
I suspect a race condition in the worker threads
89+
```
90+
91+
## Agent Capabilities
92+
93+
| Capability | Description |
94+
|------------|-------------|
95+
| **Start Debug Session** | Launch or attach to Java applications |
96+
| **Set Breakpoints** | Set conditional or unconditional breakpoints |
97+
| **Inspect Variables** | View local variables, fields, and objects |
98+
| **Evaluate Expressions** | Execute Java expressions in debug context |
99+
| **Step Through Code** | Step over, step into, step out |
100+
| **Multi-thread Support** | Debug concurrent applications |
101+
| **Stack Trace Analysis** | View and navigate call stacks |
102+
103+
## How It Works
104+
105+
The agent uses **hypothesis-driven debugging**:
106+
107+
```
108+
┌─────────────────────────────────────────┐
109+
│ 1. STATIC ANALYSIS │
110+
│ Read code, understand the problem │
111+
└─────────────────┬───────────────────────┘
112+
↓
113+
┌─────────────────────────────────────────┐
114+
│ 2. FORM HYPOTHESIS │
115+
│ "Variable X is null at line Y" │
116+
└─────────────────┬───────────────────────┘
117+
↓
118+
┌─────────────────────────────────────────┐
119+
│ 3. SET BREAKPOINT │
120+
│ At the location to verify │
121+
└─────────────────┬───────────────────────┘
122+
↓
123+
┌─────────────────────────────────────────┐
124+
│ 4. VERIFY │
125+
│ Check if hypothesis is correct │
126+
│ ├─ YES → Report root cause │
127+
│ └─ NO → Form new hypothesis │
128+
└─────────────────────────────────────────┘
129+
```
130+
131+
## Tips for Best Results
132+
133+
### Stay in Agent Mode
134+
135+
Make sure you're in **JavaDebug** agent mode (check the agent selector in Chat panel). If you switch back to default Copilot mode, the debugging tools won't be available.
136+
137+
### Be Specific
138+
139+
```
140+
✅ Good: "Why does getUserById return null when id=123?"
141+
❌ Vague: "Something is wrong"
142+
```
143+
144+
### Mention the Error
145+
146+
```
147+
✅ Good: "Getting ArrayIndexOutOfBoundsException in processItems()"
148+
❌ Vague: "Debug processItems"
149+
```
150+
151+
### Provide Context
152+
153+
```
154+
✅ Good: "The order total is $0 instead of $150 for order 456"
155+
❌ Vague: "Wrong calculation"
156+
```
157+
158+
## Troubleshooting
159+
160+
### Agent Can't Find the File
161+
162+
Make sure the Java project is properly loaded. Check that:
163+
- The Java extension is activated (look for Java icon in status bar)
164+
- The project is imported (check Java Projects view)
165+
166+
### Debug Session Won't Start
167+
168+
Ensure:
169+
- Your project compiles successfully
170+
- No other debug session is running
171+
- The main class can be found
172+
173+
### Breakpoint Not Hit
174+
175+
The agent will tell you to trigger the scenario. You need to:
176+
1. Run the part of your application that executes the code
177+
2. The breakpoint will be hit when the code path is executed
178+
179+
## Limitations
180+
181+
- Requires an active Java project with proper configuration
182+
- Cannot debug remote applications without proper attach configuration
183+
- Performance may vary with large codebases
184+
185+
## Feedback
186+
187+
If you encounter issues or have suggestions, please:
188+
- File an issue on [GitHub](https://github.com/microsoft/vscode-java-debug/issues)
189+
- Include the agent's response and your debugging request
190+
191+
## See Also
192+
193+
- [Debugger for Java Documentation](https://github.com/microsoft/vscode-java-debug)
194+
- [No-Config Debug](../scripts/noConfigScripts/README.md)
195+
- [Troubleshooting Guide](../../Troubleshooting.md)

0 commit comments

Comments
 (0)