- Overview
- Requirements & Installation
- Quick Start
- Session Window
- Sending Prompts
- Favorites
- Prompt History
- File Attachments
- Interactive Prompts (Choice Menu)
- File-Change Permissions (Diff Panel)
- Settings (Tools → Options → Claude Code)
- Profiles
- Managing Sessions
- IDE Tools (MCP)
- Troubleshooting
NetBeans Claude Code GUI is a NetBeans IDE plugin that embeds the Claude Code CLI as a full interactive terminal session directly inside the IDE. You type prompts in a dedicated session tab, Claude reads and edits your project files, and the plugin provides:
- a graphical file diff (using NetBeans' built-in diff viewer) before any change is written to disk
- a graphical panel for responding to Claude's interactive questions
IDE integration (open editors, diagnostics, current selection) is exposed to Claude via the MCP protocol so that Claude always has full context about your work.
See Installation & Build for requirements, installation steps, and build instructions.
- Right-click your project in the Projects window → Open with Claude Code.
- A session tab opens and Claude Code starts. Wait for the Claude Code prompt to appear in the terminal.
- If this is the first time running Claude Code (or the first time for this project), answer Claude's initial setup questions in the terminal or the choice panel.
- Type your first prompt in the input area at the bottom (e.g.,
Explain what this project does). - Press Ctrl+Enter (default) to send. Claude's response appears in the terminal.
The session tab contains the following areas:
Displays Claude Code output. You can also click into the terminal and interact with Claude Code directly — as if it were running in a standalone terminal. Use this when the plugin fails to detect Claude's state correctly, for example if an interactive choice panel was not shown.
Zoom — use Alt+Scroll (mouse wheel) to zoom in and out, or Ctrl+= / Ctrl+−. Press Ctrl+0 or Alt+Click Wheel (middle-click while holding Alt) to reset to the default size. The Zoom submenu is also available via right-click.
Contains the input area, ▶ Send / ✖ Cancel buttons, and ☰ History / ★ Favorites buttons.
Edit mode selector — controls how Claude handles file edits:
| Label | Internal value | Description |
|---|---|---|
| Plan Mode | plan |
Claude can discuss and plan but cannot edit files |
| Ask on Edit | default |
Claude asks for permission before each edit (default) |
| Accept on Edit | acceptEdits |
Claude applies edits automatically without asking |
Press Shift+Tab anywhere in the prompt panel to cycle through modes.
Model selector — lists the models available in the current session. Standard entries (sonnet, opus, haiku) are discovered by opening the /model menu. For Claude-compatible API, OpenAI Compatible and ChatGPT Subscription profiles, every model assigned an alias in Model Aliases (sonnet, opus, haiku or custom) also appears here, shown by its full provider ID. Selecting a model switches to it immediately.
On the right side of the status bar:
- Session state —
Startingwhile the process is initializing,Readywhen Claude is waiting for input,Workingwhile a task is in progress. - Active plan — name of the current plan file, if any (shown when Claude is operating in plan mode with a saved plan).
- Claude version — the version of the
claudeCLI detected at session start.
A multi-line text area. Wrap long prompts naturally — newlines are preserved. @path tokens are highlighted in blue (see File Attachments).
Press the configured send key (default: Ctrl+Enter) or click the ▶ Send button. The input area is cleared after sending.
You can change the send key in Tools → Options → Claude Code → General (choices: Enter, Shift+Enter, Ctrl+Enter, Alt+Enter).
Press Escape in the input area, or click the ✖ Cancel button to interrupt Claude's running task.
Press Shift+Tab anywhere in the prompt panel to cycle Claude Code's edit mode. The current mode is shown in the status bar.
- ▶ Send is active only when Claude is idle and ready to accept input.
- ✖ Cancel is active only when Claude is working.
If the states appear out of sync:
- Send is inactive but Claude is ready — click ✖ Cancel to reset the state.
- Cancel is inactive but Claude is working — click into the terminal area and interact directly.
| Item | Description |
|---|---|
| Cut / Copy / Paste / Select All / Clear | Standard text editing actions |
| Add to Favorites | Saves the current input text as a project favorite (active only when the input is non-empty and a working directory is set) |
| Favorites... | Opens the Favorites dialog |
| Start New Session | Immediately closes the current session and opens a fresh one (available only during an active session) |
| Switch to Session… | Opens the Save & Switch dialog pre-selecting "Resume specific" (available only during an active session) |
Favorites are saved prompts you can reuse with a button click or a keyboard shortcut.
- Global favorites — available in every project. Managed in Tools → Options → Claude Code → Favorites.
- Project favorites — available only for a specific working directory.
Right-click the input area → Add to Favorites. This always adds to project favorites. To promote a project favorite to global, use the To Global button in the Favorites dialog.
Click ★ Favorites in the prompt panel to open the dialog.
The dialog shows a table with the following columns:
| Column | Description |
|---|---|
| ☐ | Checkbox for multi-select |
| Text | Prompt text (truncated to 100 characters) |
| Shortcut | Assigned keyboard shortcut, if any |
| Scope | PROJECT or GLOBAL |
Buttons:
| Button | Effect |
|---|---|
| Send | Loads the selected favorite into the input area and closes the dialog (also triggered by double-click) |
| Edit | Edit the text of the selected favorite |
| To Global | Move selected PROJECT favorite(s) to global scope |
| Assign Shortcut | Assign a keyboard shortcut to the selected favorite |
| ↑ / ↓ | Change the display order of favorites |
| Delete | Delete selected favorite(s) (PROJECT only — global favorites can only be deleted via Tools → Options → Claude Code → Favorites) |
The search field filters entries by text.
Click Assign Shortcut to open the shortcut capture dialog. Press the desired key combination(s) — they are displayed in the field. Multiple key combos can be chained (e.g., Ctrl+K Ctrl+F).
If the combination is already used by another favorite, a conflict warning is shown and OK is disabled.
Note: All key presses are captured as shortcut input — to close the dialog use the OK, Clear, or Cancel buttons with the mouse.
Shortcut conflicts with other NetBeans IDE actions are not checked automatically. If a shortcut does not work, check for conflicts in Tools → Keymap (search "Claude Favorite").
The plugin records every sent prompt per working directory.
| Action | Key |
|---|---|
| Previous prompt (older) | Ctrl+Up |
| Next prompt (newer) | Ctrl+Down |
These keys work inside the input area. At the most-recent position, Ctrl+Down clears the field.
Click the ☰ History button to open the History dialog.
The dialog shows history for the current working directory. The table has the following columns:
| Column | Description |
|---|---|
| ☐ | Checkbox for multi-select |
| Prompt | Prompt text (truncated to 120 characters) |
| Time | Date and time the prompt was sent (yyyy-MM-dd HH:mm) |
Buttons:
| Button | Effect |
|---|---|
| Send | Loads the selected entry into the input area and closes the dialog (also triggered by double-click) |
| To Favorites | Saves selected entries as project favorites |
| Delete | Deletes selected entries |
| Clear older… | Opens a date input dialog (yyyy-MM-dd); deletes all entries from that date and older (with confirmation) |
The search field filters entries by prompt text.
Configure in Tools → Options → Claude Code → General:
| Setting | Default | Description |
|---|---|---|
| History max depth | 200 | Maximum entries kept per working directory |
| History TTL (days) | 0 (forever) | Entries older than this are purged automatically |
You can attach files to a prompt as @path tokens. Claude Code interprets these as file references.
Type @ anywhere in the input area. A popup appears listing the contents of the current directory level. Hidden files (starting with .) are not shown. .. is always present for navigating up.
| Key | Action |
|---|---|
| Up / Down | Navigate the list |
| Enter or Tab | File: insert and close popup. Directory: navigate into it. |
| Space | Insert the current item as-is (even if it is a directory) and close the popup |
| Escape | Dismiss the popup |
| Double-click | Same as Enter |
You can drag items from the OS file manager or the NetBeans Projects tree and drop them onto the input area, or paste them via Ctrl+V, Shift+Ins, or Paste from the context menu.
Three types of content are supported:
| Content type | What is inserted |
|---|---|
| File inside the working directory (from OS or Projects tree) | Relative path without @ (e.g. src/Main.java) |
| File outside the working directory | @/absolute/path |
Package directory (under a source root such as src/main/java/) |
Fully-qualified package name (e.g. com.example.util) |
| Directory inside the working directory (not a source root) | Relative path without @ |
| Directory outside the working directory | @/absolute/path |
| Image from clipboard | Saved as a temporary PNG file; @/tmp/....png inserted |
| Plain text | Inserted as-is |
Claude Code sometimes presents interactive prompts (Yes/No or multiple choice). The plugin detects these and shows a Choice Menu panel in place of the prompt input area.
Yes / No options appear as buttons. Clicking one sends the answer immediately and closes the panel.
Other options appear as radio buttons. Some options may include a text field for additional input. Click the desired option (and optionally fill in the text field), then press Enter or click Send to submit. Press Escape to cancel.
Long menus. When Claude shows only part of a long list (e.g. /model with more than a handful of models), the plugin scrolls through the whole list once to collect every item, then shows them all. If the list is taller than Choice menu max height (see Settings), the option list gets a scrollbar. Items numbered 10 and above are selected by moving Claude's cursor with the arrow keys, so every item can be chosen.
After submitting or cancelling, the input area is restored automatically.
Note: If the choice panel does not appear when Claude asks a question, or appears unexpectedly without a question — click into the terminal area and interact with Claude directly. The panel will disappear automatically once Claude's state changes.
When Claude Code is about to edit or create a file, the plugin intercepts the operation and shows a diff panel before the change is written to disk.
The diff panel appears either embedded in the session tab (replacing the input area) or in a separate IDE tab, depending on the setting in Tools → Options → Claude Code → General → Open file diff in a separate tab.
[✓✓ Accept All] [✓ Accept] [_Decline reason (Optional)_] [✗ Decline] [Cancel]
| Button | Effect |
|---|---|
| ✓✓ Accept All | Accept this change and switch Claude's edit mode to "Accept on Edit" for this session — all subsequent edits are accepted automatically without showing a diff |
| ✓ Accept | Allow this single change; Claude continues |
| ✗ Decline | Reject this change; optionally send a reason to Claude (type it in the text field first) |
| Cancel | Reject this change and interrupt Claude's current task |
| Close tab (×) | Treated as Decline without a reason |
| Situation | Action |
|---|---|
| You agree with all the proposed changes | Click ✓ Accept (or ✓✓ Accept All to skip diffs for all further edits in this session) |
| You disagree completely — the change should not be made at all | Click ✗ Decline (optionally explain why in the reason field) |
| You partially agree — the change is on the right track but needs adjustment | Type what needs to be different in the reason field, then press Enter or click ✗ Decline. Claude will receive your feedback and try again. |
Type a reason in the text field between the Accept and Decline buttons. When you click Decline, the reason is sent to Claude. Pressing Enter in a non-empty reason field automatically clicks Decline.
If you type a decline reason but click Accept, a confirmation dialog warns you that the reason will not be sent.
Tab / Shift+Tab cycles focus between: Accept All → Accept → reason field → Decline → Cancel. Press Escape to click Cancel.
For .md files, a rendered markdown preview is shown alongside the raw diff. Toggle it via right-click on the diff → Preview Markdown (checkbox). The default state is configured in Tools → Options → Claude Code → General → Markdown preview in diff, which offers three options:
| Option | Behaviour |
|---|---|
| Always | Always show the inline preview for .md files in the diff panel (default) |
| Never | Never show the inline preview |
| Except when Plan Preview tab is open | Show the inline preview, but suppress it when a dedicated live Plan Preview tab is already visible for a file in the plans/ directory |
Toggling in the context menu does not change the global setting.
Pin Preview — opens the rendered markdown (proposed content) in a separate IDE tab that remains open after the diff is closed.
Both features are especially useful in Claude's plan mode: they let you read the formatted plan before deciding whether to accept it.
These controls apply to every Markdown Preview tab — whether shown inside the diff panel, opened by the show_markdown / show_markdown_file MCP tools, or the Auto Plan Preview tab.
| Action | Key / gesture |
|---|---|
| Open find bar | Ctrl+F |
| Next match | F3 |
| Previous match | Shift+F3 |
| Close find bar | Escape |
| Reload from disk | F5 |
| Zoom in | Alt+Scroll up or Ctrl+= |
| Zoom out | Alt+Scroll down or Ctrl+− |
| Reset zoom | Ctrl+0 or Alt+Click Wheel |
| Zoom submenu | Right-click → Zoom |
When Claude writes a plan file to a plans/ directory (e.g. ~/.claude/plans/my-plan.md), the plugin can automatically open a live Markdown Preview tab the moment you click Accept in the diff panel.
- The preview opens immediately when you click Accept; the file content appears within a second or two as Claude finishes writing it.
- If you click Accept again for the same plan file (e.g. after an update), the existing preview tab refreshes in-place instead of opening a new tab.
- The feature works with any
CLAUDE_CONFIG_DIRlocation — it detects theplans/directory by name, so named profiles with custom config directories are supported automatically.
Enable / disable: Tools → Options → Claude Code → General → Automatically open Plan Preview tab when Claude writes a plan.
If the file being edited is outside the current project directory, a warning ⚠ is shown in the diff panel.
Open Tools → Options → Claude Code in NetBeans.
| Setting | Default | Description |
|---|---|---|
| Start new session when opening with Claude | Off (Continue last) | Checked → always start a New session when opening with the project context menu or when NetBeans restores a closed session tab on restart. Unchecked → Continue last. |
| Session tab dock position | Editor area | Where the Claude Code session tab is docked when first opened. Choices: Editor area, Right side, Left side top, Left side bottom, Bottom dock. |
| Send prompt key | Ctrl+Enter | Key combination that sends the prompt from the input area. |
| Insert newline key | Enter | Key combination that inserts a newline in the input area. The send and newline keys are configured independently but cannot be set to the same value. |
| Open file diff in a separate tab | Off | Opens the diff panel in a new IDE tab instead of embedding it in the session tab. |
| File diff tab dock position | Editor area | Where the File Diff tab is docked when opened as a separate tab. Enabled only when "Open file diff in a separate tab" is checked. |
| Markdown preview in diff | Always | Controls when the inline markdown preview is shown for .md files in the diff panel. Always — always show it. Never — never show it. Except when Plan Preview tab is open — show it, but suppress it when the diffed file is a plan file and Auto Plan Preview is on (or its tab is already open). |
| Automatically open Plan Preview tab when Claude writes a plan | On | When enabled, a live Markdown Preview tab opens automatically as soon as the user clicks Allow in a diff panel for a file in a plans/ directory. |
| Markdown preview dock position | Right side | Where the Markdown Preview tab is docked when first opened. Choices: Editor area, Right side, Left side top, Left side bottom, Bottom dock. |
| Choice menu focus | Grab focus | Controls whether the choice menu panel grabs keyboard focus when it appears. Choices: Grab focus, Show without grabbing focus, Hide menu. |
| Choice menu max height (px) | 320 | Maximum height of the option list in the choice menu panel (100–2000). Longer lists (e.g. /model with many models) get a scrollbar; the scrollbar also appears or disappears by itself when you resize the panel by dragging the divider. |
| Terminal font | Auto | Font used in the embedded terminal. Click Choose… to open the font picker. The label shows the resolved font name (e.g. Adwaita Mono, 14 (Auto) when auto-detection is active, or Monospaced, 14 when set explicitly). |
The Choose… button opens a font picker dialog:
- Font list — all installed font families. The first item, Auto (detect best available), lets the plugin choose automatically.
- Show monospaced only checkbox — filters the list to monospace fonts (checked by default).
- Size spinner — font size, 8–72 pt.
- Preview — renders
AaBbCc 0O1Il → ⏵ ◐in the selected font and size, so you can verify that Claude Code TUI symbols (spinner, prompt marker) are covered.
When Auto is selected, the plugin picks the first installed font from this priority list: Adwaita Mono, Consolas, Menlo, DejaVu Sans Mono, Monospaced. Adwaita Mono has the broadest Unicode coverage for Claude Code TUI symbols; on Linux GNOME desktops it is usually pre-installed.
| Setting | Default | Description |
|---|---|---|
| Claude CLI path | (empty) | Absolute path to the claude executable. Leave empty to use the system PATH. |
| Hang timeout (seconds) | 60 | Kill the process if no PTY output is received within this many seconds after launch. Set to 0 to disable. |
| MCP server port | 28991 | Port for the internal MCP SSE server. Change only if 28991 conflicts. Requires IDE restart. |
| Enable MCP integration | On | When unchecked, the --mcp-config flag is not passed to claude. Hooks (PreToolUse) are always configured regardless of this setting. Disable only if MCP causes issues. |
| History max depth | 200 | Maximum number of history entries kept per working directory. |
| History TTL (days) | 0 | Number of days after which history entries expire. 0 = keep forever. |
| Session list limit | 30 | Maximum number of past sessions shown in the session selector table. |
| Debug mode | Off | Enables verbose logging of all Claude I/O to the NetBeans log file and the Output window. |
Manages global favorites — prompts available in every project.
The table shows all global favorites with columns: ☐ (checkbox for multi-select), Text, Shortcut.
Buttons:
| Button | Effect |
|---|---|
| Add | Add a new global favorite (enter text in the dialog) |
| Edit | Edit the text of the selected favorite |
| Assign Shortcut | Assign a keyboard shortcut to the selected favorite |
| ↑ / ↓ | Change the display order |
| Delete | Delete selected favorite(s) |
The search field filters entries by text.
See Section 12 — Profiles for full details on creating and managing profiles.
Profiles allow you to run Claude Code under different accounts for different projects. Each profile has an isolated CLAUDE_CONFIG_DIR so that authentication and settings do not interfere with each other.
Open Tools → Options → Claude Code → Profiles.
The Default profile is always present and cannot be renamed or deleted. Named profiles can be freely created, copied, renamed, and deleted.
Named profiles are stored under a common base directory (default: ~/.netbeans/claude-plugin/profiles/). Each profile occupies a subdirectory named after the profile.
The base directory only affects newly created profiles. To move existing profiles to a new location, manually move their subdirectories to the new location first, then update the directory via the New Profiles Directory field (click Change…).
The Profile Storage Directory field shows where Claude Code stores its configuration
for the selected profile. For the Default profile it shows ~/.claude (not overridden)
and the buttons are disabled. For named profiles:
- Computed path (default) —
<profilesDir>/<profile-name>. The field shows the path with no suffix. - Custom path — any directory you choose. The field shows the path with a
(custom)suffix.
| Button | Effect |
|---|---|
| Change… | Opens a directory chooser. The chosen path is stored with the profile and used as CLAUDE_CONFIG_DIR when a session starts. |
| Reset | Clears the custom path and reverts to the computed default. Enabled only when a custom path is set. |
Tip: Use a custom path to share a single Claude Code configuration directory across multiple profiles, or to point a profile at an existing
~/.claude-style directory.
| Button | Effect |
|---|---|
| New | Create a new named profile |
| Copy | Duplicate the currently selected profile |
| Rename | Rename the currently selected profile |
| Delete | Delete the currently selected profile |
Select the authentication type using the radio buttons:
| Type | Fields to fill in | How to authenticate |
|---|---|---|
| Claude Managed | None | Claude manages authentication itself. Run claude in a terminal once to set it up, or Claude will prompt you on first launch. Use /login in the session terminal to re-authenticate. |
| Claude Subscription | OAuth token | Obtain the token at claude.ai (requires Pro, Max, Team, or Enterprise subscription). Note: OAuth tokens expire periodically and must be regenerated and re-entered manually. For a smoother experience, prefer Claude Managed instead. |
| Claude API | API key | Obtain the key at console.anthropic.com (requires an Anthropic Console account with API access). |
| Claude-compatible API | API key + Base URL | Use the API key and base URL provided by your third-party provider (Anthropic-compatible endpoint). |
| OpenAI-compatible API | API key + Base URL | Route Claude Code through any OpenAI-compatible provider. The plugin starts an internal proxy that translates Anthropic API calls to OpenAI Chat Completions format. See OpenAI-compatible API below. |
| ChatGPT Subscription | Sign in via browser | Route Claude Code through OpenAI's Codex backend using a ChatGPT Free, Go, Plus, Pro, or Team subscription instead of an API key. See ChatGPT Subscription below. |
Note: Changes to connection parameters (API key, Base URL) take effect only after restarting the session.
If your provider names models differently from Anthropic's standard names, the plugin cannot match them to the sonnet, opus, and haiku aliases used by Claude Code. In that case, set the alias to the actual model ID used by your provider (for example, with an anthropic/ prefix). For ChatGPT Subscription, Model Aliases… becomes available once you're signed in and fetches the live list of models available to your account instead of a fixed list.
Click Model Aliases… to open the Model Aliases dialog.
The dialog shows a table with four columns:
| Column | Description |
|---|---|
| ID | The model identifier as returned by the provider |
| Available | ✓ if the model was found at the endpoint during the last Fetch; ✗ otherwise |
| Alias | The standard alias to map this model to: sonnet, opus, haiku, custom, or blank (no alias) |
| Explicit Cache | Experimental: send explicit prompt-cache control to the provider for this model (see below) |
Explicit Cache column (experimental): GPT-5.6-family models changed how automatic prompt caching works, making it unreliable for long conversations with a stable system prompt and a growing message history — exactly the pattern of an ongoing coding session (see ChatGPT Subscription rate limits below for background). Checking this column sends explicit cache-control fields to the provider for that model: GPT-5.6+ models get an explicit cache breakpoint (limited to a 30-minute cache lifetime by the provider); older GPT models get a 24-hour cache retention hint instead. It's checked by default for GPT-5.6-family model IDs and has no effect for non-GPT models (e.g. Grok, Gemini) — their own caching, if any, is unaffected. Since this relies on provider behavior that isn't fully documented, treat it as experimental — uncheck it for a model if you notice no improvement or unexpected errors. It applies to the OpenAI Compatible connection type only: for ChatGPT Subscription the column has no effect, because the ChatGPT Codex backend rejects explicit cache-control fields — caching there is automatic, keyed to your Claude Code session.
Buttons:
| Button | Effect |
|---|---|
| Fetch | Queries the provider's models endpoint (using the configured API key, or your signed-in ChatGPT session for ChatGPT Subscription), fills the table with discovered model IDs, and marks each as available (✓) or unavailable (✗) |
| Add | Opens an input dialog; enter a model ID to append a new row to the table (with blank alias and no availability mark) |
| Rename | Opens an input dialog pre-filled with the selected row's ID; confirm to update the model ID in place |
| ↑ / ↓ | Reorder rows — the order determines how models appear in the status bar model selector |
| Sort | Sort all rows alphabetically by model ID (case-insensitive) |
| Delete | Remove the selected row |
| Prune | Remove all rows marked as unavailable (✗) |
How to configure aliases:
- Click Fetch to populate the table with models available at your endpoint.
- For each model you want to use as a standard model (
sonnet,opus, orhaiku), set the corresponding alias. You can skip this step if the model ID already starts withsonnet,opus, orhaiku— those are matched automatically. Claude Code also uses these aliases on its own — e.g. many subagents run onhaikuand background requests onsonnet— so with ChatGPT Subscription and OpenAI Compatible profiles map all three, otherwise those requests fail with an unsupported-model error. A model mapped to an alias still appears in the model selector under its own ID. - For each additional model you want to appear in the model selector, set its alias to
custom. You can assigncustomto as many models as you like — each will appear as a separate entry in the selector. - Leave models you do not plan to use with a blank alias, or remove them with Delete / Prune.
The custom alias: Unlike the other aliases, custom is not unique — multiple models can share it. All models with the custom alias appear as individual entries in the model selector in the status bar, identified by their full provider ID. Selecting one sends /model <id> to Claude.
Note: Not all third-party models are compatible with Claude Code. Using an incompatible model may cause errors or unexpected behavior during the session.
| Mode | Description |
|---|---|
| System managed (default) | Claude Code inherits proxy settings from the IDE environment. Use this when a proxy is already configured in the system. |
| No proxy | Forces Claude Code to connect directly, bypassing any system proxy. |
| Custom | Specify proxy settings manually. Use this when Claude Code needs a proxy different from the system default. |
Custom proxy fields:
| Field | Syntax | Example |
|---|---|---|
| HTTP Proxy | http://host:port |
http://proxy.example.com:8080 |
| HTTPS Proxy | http://host:port |
http://proxy.example.com:8080 |
| NO_PROXY | Empty or a comma-separated list of host patterns | localhost,127.0.0.1,.example.com |
Note: Claude Code communicates with the plugin via localhost. External proxies are not aware of this. If you fill in the NO_PROXY field, make sure it includes localhost — otherwise the plugin integration will stop working. If you leave the field empty, the plugin adds localhost automatically.
Claude Code sends requests in Anthropic Messages API format. Many AI providers — including OpenAI, Azure OpenAI, Groq, DeepSeek, and local models via Ollama or LM Studio — use OpenAI Chat Completions format instead. The OpenAI-compatible API connection type bridges this gap by running an internal HTTP proxy inside the plugin.
How it works:
- When a session starts, the plugin registers an internal proxy path within the already-running MCP server.
- Claude Code is directed to send requests to that path (
ANTHROPIC_BASE_URL=http://127.0.0.1:<mcp-port>/openai-proxy/<session-id>). - The proxy translates each Anthropic Messages API request to OpenAI Chat Completions format, forwards it to your provider, and translates the response back — including streaming and tool calls.
- When the session stops, the proxy path is deregistered. No separate port or process is used.
Setup:
- Create a new profile and select OpenAI-compatible API as the connection type.
- Fill in Base URL — the base URL of your provider's API (e.g.
https://api.openai.com/v1,http://localhost:11434/v1for Ollama). - Fill in API Key — the API key for your provider (enter any non-blank value if the provider does not require a key).
- Open Model Aliases… and map Claude model tiers to your provider's model names:
| Alias | Provider model example |
|---|---|
sonnet |
gpt-4o |
opus |
gpt-4o |
haiku |
gpt-4o-mini |
Without model aliases, Claude Code will send Anthropic model names (e.g. claude-sonnet-4-5) to your provider. Most OpenAI-compatible providers will reject these — configure aliases to avoid errors.
Provider examples:
| Provider | Base URL | Notes |
|---|---|---|
| OpenAI | https://api.openai.com/v1 |
Standard OpenAI key |
| Azure OpenAI | https://<resource>.openai.azure.com/openai/deployments/<deployment> |
Azure API key |
| Groq | https://api.groq.com/openai/v1 |
Groq API key |
| DeepSeek | https://api.deepseek.com/v1 |
DeepSeek API key |
| Ollama (local) | http://localhost:11434/v1 |
Any value for API key |
| LM Studio (local) | http://localhost:1234/v1 |
Any value for API key |
Limitations:
- Not all OpenAI-compatible models support all Claude Code features (tool use, large context windows). Using an incompatible model may cause errors.
- Images in conversations (base64 content) are forwarded in OpenAI vision format; provider must support it.
- Changes to the profile's Base URL or API Key take effect only after restarting the session.
Routes Claude Code through OpenAI's own Codex backend using your ChatGPT Free, Go, Plus, Pro, or Team subscription, instead of an OpenAI API key. Like OpenAI-compatible API, this works via the plugin's internal proxy — no changes to Claude Code CLI are required.
How it works:
The plugin never opens or waits on a browser itself, since the browser you sign in with may be on a different network path (proxy, VPN, remote machine) than the plugin. Instead:
- Click Copy sign in link — the plugin generates a one-time sign-in link and copies it to the clipboard.
- Paste the link into your own browser and sign in to your ChatGPT account there.
- After signing in, copy the code shown on the confirmation page and paste it back into the field in the plugin.
- Click Complete Sign-in. The profile now shows Signed in as
<email>.
You can click Copy sign in link again at any time to cancel a stuck attempt and generate a fresh link — there is no timeout to wait out.
Setup:
- Create a new profile and select ChatGPT Subscription as the connection type.
- Sign in as described above.
- Open Model Aliases… and click Fetch to pull the current list of models available to your account, then assign aliases the same way as for OpenAI-compatible API above.
Limitations:
- Only models Codex actually supports for a ChatGPT-subscription login work — arbitrary model IDs will be rejected by OpenAI's backend.
- Usage is subject to your ChatGPT subscription's own rate limits, shared across all Codex/ChatGPT clients on that account. When the limit is reached, Claude Code now reports it immediately as a rate-limit error instead of retrying; the message doesn't currently include the exact reset time reported by the backend.
- The
/usagecommand shows only local, per-session statistics (tokens/cost for the current conversation) — it does not query any live account-wide usage or quota endpoint, so it never reflects your ChatGPT subscription's remaining quota or reset time, for any connection type. - Sign-in tokens are refreshed automatically while a session is running; if a refresh fails (e.g. the session was revoked from your OpenAI account), sign in again from the Profiles tab.
Arbitrary KEY=VALUE pairs injected into the Claude process environment. Applied last — they override all other profile variables. Use this for provider-specific configuration.
See the Claude Code environment variables reference for the full list of supported variables, and third-party integrations for compatible API providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry, and others).
An optional space-separated list of command-line flags and values appended to the claude command when starting a session. Use this for flags that are not exposed elsewhere in the plugin settings.
Example:
--debug --max-turns 5
Arguments that contain spaces can be wrapped in double quotes:
--system "You are a concise assistant"
Arguments are appended after all internally generated arguments. Refer to claude --help for the full list of supported flags.
By default, Claude Code sessions use the Default profile.
To permanently assign a profile to a project:
- Right-click the project in the Projects window → Properties.
- Go to the Claude Code category.
- Select the desired profile from the Profile drop-down and click OK.
The selected profile is used automatically when a session is started for that project via Open with Claude Code. Selecting Default removes any project-specific assignment.
If the assigned profile no longer exists, the plugin falls back to the Default profile automatically.
Click the Claude Code button in the toolbar to open the session selector. Choose a project or a working directory, select a profile from the Profile combo, and click Open. The selected profile is used for that session only and does not affect project settings. See Managing Sessions for full details of the session selector panel.
Sessions let you save your current conversation with Claude, switch to a different task, and come back to the saved session later. For example: you are working on a refactor with Claude, need to quickly fix an unrelated bug, then want to return to the refactor — sessions make this seamless.
Claude Code remembers your past conversations as sessions. The session mode determines which conversation is loaded — a new empty one, the most recent saved one, or a specific one you choose from a list.
| Mode | When to use |
|---|---|
| New session | Start a fresh conversation |
| Continue last | Resume the most recent session for this working directory |
| Resume specific | Return to a specific past session chosen from a list |
Project context menu (right-click → Open with Claude Code) — the mode is fixed by the Start new session when opening with Claude setting: checked = New session, unchecked = Continue last. Resume specific is not available from the context menu.
Toolbar button — you pick the mode explicitly in the session selector panel before opening.
The session selector panel is shown in a session tab opened via the Claude Code toolbar button. It is not shown when opening via the project context menu (the session starts immediately in that case).
Fields:
- Project — combo listing open NetBeans projects; selecting one fills the path automatically.
- Path — editable combo with recently used paths + Browse button to pick a directory.
- Profile — selects which API key/proxy profile to use (see Profiles).
- Extra args — additional CLI flags for this session only. Pre-filled from the selected profile's extra CLI arguments; editable here without affecting the profile.
- Mode — radio buttons: New session / Continue last / Resume specific.
- Session table (visible only when "Resume specific" is selected) — lists past sessions for the chosen working directory, columns: Date/Time, Name, First Prompt. Click a row to select it, then click Open. Use the Rename button to give a session a custom title. The list is loaded when you switch to "Resume specific" mode and reloads automatically when you change the working directory or profile. The number of sessions shown is limited by the Session list limit setting (default: 30); increasing the limit may slow down loading.
Click Open to apply the settings and open the session. When "Resume specific" is selected, you can also double-click a row in the session table to open that session immediately.
While a session is running, you can close it and, optionally, open a different one.
Closing the tab (× on the tab header) — closes the session immediately without any confirmation. The conversation is automatically saved by Claude Code and can be resumed later using "Resume specific" mode.
Close button (⏻) in the status bar → opens the Save & Switch dialog:
- Session name field — pre-filled with the current session name. Giving a session a descriptive name makes it easier to find it later in the session list when using "Resume specific".
- Mode panel — choose what happens next:
- Close only — stop the session and close the tab. The conversation is saved and can be resumed later.
- Restart Advanced... — stop the session and return to the session selector panel in the same tab, allowing full reconfiguration (directory, profile, mode) before starting a new session.
- New session / Continue last / Resume specific — stop and immediately start another session in the same tab. For Resume specific, a session table is shown — see Session selector panel for details.
- Click OK to close (and optionally rename) the session and open the next one as chosen. When "Resume specific" is selected, you can also double-click a row in the session table to confirm immediately.
Context menu in the input area (right-click, available only during an active session) provides two quick actions:
- Start New Session — immediately closes the current session and opens a fresh one (no rename, no dialog).
- Switch to Session… — opens Save & Switch pre-selecting "Resume specific".
Note on
/clear: The/clearcommand clears Claude's context within the current session — after that, the previous conversation context is permanently gone and cannot be resumed. To pause your current work and switch to another task temporarily, use Save & Switch → New session instead. The original session will remain intact and can be resumed later.
When to use what:
| Situation | How |
|---|---|
| Save current session and start a fresh one (can return later) | Via ⏻: optionally fill in a session name → New session → OK Via context menu: right-click input area → Start New Session (no rename option) |
| Start fresh without being able to return to current context | Type /clear in the input area and send it |
| Switch to a specific past session | ⏻ → Resume specific → pick session → OK (or double-click the row) or: right-click input area → Switch to Session… → pick session |
| Close tab, keep session for later | × on the tab or: ⏻ → Close only → OK or: ⏻ → fill in a session name → Close only → OK |
| Stop session, reconfigure everything, then start | ⏻ → Restart Advanced... → OK — returns to the selector panel in the same tab |
Sessions can be renamed in three places:
- Session selector table — select a row and click Rename.
- Save & Switch dialog → session table (when "Resume specific" is selected) — select a row and click Rename.
- Save & Switch dialog → Session name field — renames the currently running session when you close it.
A custom name replaces the auto-generated name in all session lists.
When you restart the IDE, the plugin automatically restores any session tabs that were open and reopens them with the same working directory, profile, and extra args.
The session mode used on restore depends on how the session was last opened:
- If the session was opened with Resume specific — the same specific session is resumed again (the saved session ID is restored).
- Otherwise (New session or Continue last) — the mode is determined by the Start new session when opening with Claude setting at the time of restart.
The plugin exposes a set of IDE tools to Claude via an MCP (Model Context Protocol) server that runs in the background. These tools give Claude real-time access to your IDE state — open projects, open files, current selection, diagnostics — so it can give more relevant answers and take actions directly in the editor.
| Tool | What it does |
|---|---|
getWorkspaceFolders |
Lists all open projects with their paths |
getOpenEditors |
Lists all currently open editor tabs |
getCurrentSelection |
Returns the selected text and cursor position in the active editor |
getDiagnostics |
Returns errors and warnings for specified files |
openFile |
Opens a file in the editor |
close_tab |
Closes an open editor tab |
checkDocumentDirty |
Checks whether a file has unsaved changes |
saveDocument |
Saves a file to disk |
openDiff |
Shows a git diff for a file in the diff viewer |
closeAllDiffTabs |
Closes all open diff viewer tabs |
permission_prompt |
Shows proposed file changes in the diff panel and waits for your approval |
show_markdown |
Renders markdown text directly in a Markdown Preview tab; accepts the markdown content plus optional title and file path |
show_markdown_file |
Opens a live-updating Markdown Preview tab for an existing .md file on disk; the tab automatically refreshes when the file changes |
Project and file context:
- "What projects are currently open?"
- "List all files I have open right now."
- "Open the test file for this class."
Current selection (select code first, then send the prompt):
- "Explain this code."
- "Write a unit test for this method."
- "What does this do and how can it be improved?"
Diagnostics:
- "Fix all errors in this project."
- "What warnings are in
src/main/java/com/example/Foo.java?" - "There are compile errors in the open files — fix them."
As you move the cursor or change the selection in any open editor, the plugin automatically notifies Claude of the current file and position. Claude always knows what you are looking at without you needing to mention it in the prompt.
If Claude says a tool is unavailable (e.g. "I don't have access to getWorkspaceFolders"):
- Check that no other application is using the MCP server port (Tools → Options → Claude Code → Advanced → MCP server port, default: 28991). Change the port if needed and restart the IDE.
- Enable Debug mode (Tools → Options → Claude Code → Advanced) and check the log file (
~/.netbeans/<version>/var/log/messages.log) forMCP SSE server started on port.
Go to Tools → Options → Claude Code → Advanced and check Debug mode. This writes detailed logs of all Claude I/O (PTY bytes, MCP messages, hook calls) to the NetBeans log file.
~/.netbeans/<version>/var/log/messages.log
For example: ~/.netbeans/28/var/log/messages.log
| Symptom | Likely cause | Fix |
|---|---|---|
| Session tab does not open | claude not found on PATH |
Set the full path in Tools → Options → Claude Code → Advanced → Claude CLI path |
| Diff panel shows but Accept/Decline have no effect | Claude timed out waiting for the hook response (600 s limit) | Respond to the diff panel within ~9 minutes; if this happens regularly, check for blocking processes |
| Claude asked a question but the Choice Menu panel did not appear | The plugin did not recognise the prompt format | Switch to the terminal area and answer directly by typing |
| Choice Menu appeared but Claude did not ask anything (false trigger) | The plugin mis-detected a numbered list as a menu | Dismiss the panel with Esc or ignore it; Claude will continue on its own |
| OAuth login prompt not appearing | The claude process cannot open a browser, or proxy settings mismatch |
Run claude manually in a terminal once to complete authentication, then restart the session. If you use a proxy, make sure the proxy settings in the plugin profile match the system/browser proxy settings. |
| Profile not applied to a project | Project properties not saved | Re-open the project properties, select the profile, and click OK. Alternatively, open the session via the toolbar and select the profile explicitly in the session selector. |
| Favorites shortcut not working | Shortcut conflicts with another IDE action | Re-assign the shortcut in Tools → Keymap (search "Claude Favorite") |
Please open an issue at the project's GitHub repository and attach the relevant section of messages.log with debug mode enabled.