中文 | English
DebugTools AI teaches Codex, Claude Code, OpenCode, Gemini, Cursor, Kimi, Pi, and other agents how to use DebugTools IntelliJ MCP tools to attach JVMs, generate method argument templates, invoke Java methods, and start IntelliJ run configurations with DebugTools Hotswap.
Install for Codex:
curl -fsSL https://raw.githubusercontent.com/future0923/debug-tools-ai/main/install.sh | bash -s -- --codexVerify the install:
debug-tools-ai doctorAsk your agent:
Use DebugTools to call com.demo.UserController.getUser.
Expected agent path:
list_debug_tools_connections
generate_method_args_template # only when parameters are needed or unclear
invoke_java_method
Hotswap start path:
list_debug_tools_run_configurations # only when the run configuration name is unknown or ambiguous
execute_debug_tools_run_configuration
If there is no active DebugTools connection, the agent should use:
list_attachable_jvms
attach_local_jvm
invoke_java_method
Agents using this package can:
- inspect current DebugTools connections
- list attachable JVM processes
- attach the DebugTools agent to a local JVM
- generate DebugTools
argsJsontemplates from Java method signatures - invoke Java methods through DebugTools
- list IntelliJ run configurations for DebugTools Hotswap launch
- start a run configuration with the DebugTools Hotswap executor
- recover from ClassLoader issues through DebugTools HTTP when needed
- IntelliJ IDEA with the DebugTools plugin installed.
- DebugTools MCP tools available from the IntelliJ plugin.
- A target JVM that is already connected or attachable.
- An AI client that can use the DebugTools MCP tools.
This package does not install IntelliJ IDEA, the DebugTools plugin, the DebugTools agent, or MCP server support.
One-line install:
curl -fsSL https://raw.githubusercontent.com/future0923/debug-tools-ai/main/install.sh | bash -s -- --codexClone install:
git clone https://github.com/future0923/debug-tools-ai.git
cd debug-tools-ai
bash install.sh --codexInstall every local integration:
bash install.sh --allAfter npm publication:
npm install -g debug-tools-ai
debug-tools-ai upgrade --allUninstall one integration:
debug-tools-ai uninstall --codexDetailed install notes: docs/installation.md.
| Agent | Local install |
|---|---|
| Codex | bash install.sh --codex |
| Claude Code | bash install.sh --claude |
| Gemini | bash install.sh --gemini |
| OpenCode | bash install.sh --opencode |
| Cursor | bash install.sh --cursor |
| Kimi | bash install.sh --kimi |
| Pi | bash install.sh --pi |
| Generic agents | Use AGENTS.md |
Marketplace and host-specific installs may require host review after publication.
| Command | Purpose |
|---|---|
debug-tools-ai install --codex |
Install one local integration. |
debug-tools-ai install --all |
Install every supported local integration. |
debug-tools-ai upgrade --all |
Reinstall local integrations from the current package. |
debug-tools-ai uninstall --codex |
Remove one local integration. |
debug-tools-ai uninstall --all |
Remove every supported local integration. |
debug-tools-ai doctor |
Check package files and installed adapter paths. |
debug-tools-ai validate |
Run the full validation suite. |
debug-tools-ai pressure |
List skill behavior pressure scenarios. |
debug-tools-ai pressure-report |
Generate a pressure run report template. |
debug-tools-ai prepublish-check |
Run release checks before publishing. |
If you are running from a checkout, use bash bin/debug-tools-ai <command>.
Run:
debug-tools-ai doctorOK means the expected file exists. WARN means an optional local adapter is not installed in the current HOME. FAIL means a required package file is missing, or --strict-installed was used and an installed adapter path is missing.
Strict installed-path check:
debug-tools-ai doctor --strict-installedNo-arg method:
User: Use DebugTools to call com.demo.HealthController.ping.
AI: list_debug_tools_connections -> invoke_java_method
Parameterized method:
User: Call com.demo.UserController.createUser with name Codex and age 18.
AI: list_debug_tools_connections -> generate_method_args_template -> invoke_java_method
ClassLoader recovery:
ClassNotFoundException: com.demo.UserController
AI: GET /allClassLoader -> POST /classLoader/hasClass -> invoke_java_method with classLoaderIdentity
If multiple ClassLoaders can load the target class, the agent must ask the user which loader identity to use instead of guessing.
Hotswap run configuration:
User: Start the DemoApplication run configuration with DebugTools Hotswap.
AI: execute_debug_tools_run_configuration configurationName=DemoApplication
If the run configuration name is unclear, the agent should call list_debug_tools_run_configurations first. A successful execute response means startup was requested; it does not prove that DebugTools is already connected.
More examples: docs/examples.md. Install transcripts: docs/transcripts.md. Chinese docs: docs/installation-zh.md, docs/examples-zh.md, docs/transcripts-zh.md. Spring Boot demo: examples/spring-boot-demo.md.
Method invocation skill:
skills/debug-tools-method-invocation/SKILL.md
Core method invocation sequence:
list_debug_tools_connections
list_attachable_jvms
attach_local_jvm
generate_method_args_template
invoke_java_method
Hotswap skill:
skills/debug-tools-hotswap/SKILL.md
Core Hotswap sequence:
list_debug_tools_run_configurations
execute_debug_tools_run_configuration
Details:
- Workflow: docs/workflow.md
- Tool contracts: docs/tool-contracts.md
- Method invocation skill: skills/debug-tools-method-invocation/SKILL.md
- Hotswap skill: skills/debug-tools-hotswap/SKILL.md
Run:
bash scripts/validate.shFocused checks:
bash bin/debug-tools-ai validate
bash scripts/check-versions.sh
bash scripts/check-manifest-paths.sh
bash scripts/smoke-install.sh
bash scripts/check-pressure-scenarios.sh
bash scripts/check-release-readiness.shPressure scenarios live in tests/pressure. Use them with a fresh AI agent when changing skill behavior.
- Contributing: CONTRIBUTING.md
- Release process: docs/release.md
Before publishing:
bash bin/debug-tools-ai prepublish-checkRelease requires version updates, CHANGELOG.md, git tag, GitHub Release, and host-specific marketplace submission where applicable. The release workflow uses softprops/action-gh-release.