Skip to content

Commit 71c59e3

Browse files
wenytang-mswenytang-ms
committed
docs: readme
1 parent 65667ec commit 71c59e3

File tree

7 files changed

+202
-7
lines changed

7 files changed

+202
-7
lines changed

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +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-
- **[NEW]** No-Config Debug (debug Java apps without launch.json)
21-
- **[NEW]** AI-Assisted Debugging (GitHub Copilot integration)
20+
- No-Config Debug (debug Java apps without launch.json)
21+
- **[AI]** AI-Assisted Debugging (GitHub Copilot integration)
2222

2323
## Requirements
2424
- JDK (version 1.8.0 or later)
@@ -73,7 +73,7 @@ The AI will automatically:
7373
2. Build/compile your project
7474
3. Start debugging with appropriate configuration
7575

76-
See [Language Model Tool Documentation](docs/LANGUAGE_MODEL_TOOL.md) for more details.
76+
See [Language Model Tool Documentation](bundled/agents/README.md) for more details.
7777

7878
## Options
7979

‎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)

‎bundled/agents/images/agent-working.png‎

91 KB
Loading

‎bundled/agents/images/invoke-agent.png‎

5.42 KB
Loading

‎bundled/agents/images/javadebug.png‎

41.2 KB
Loading

‎package-lock.json‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"name": "vscode-java-debug",
33
"displayName": "Debugger for Java",
44
"description": "A lightweight Java debugger for Visual Studio Code",
5-
"version": "0.58.4",
5+
"version": "0.58.3",
66
"publisher": "vscjava",
77
"preview": false,
88
"aiKey": "67d4461e-ccba-418e-8082-1bd0acfe8516",

0 commit comments

Comments
 (0)