Gemini CLI

Give Gemini CLI access to DebugBundle incidents, deterministic debug bundles, reproductions, endpoint health, and aggregate product analytics while it works in your application repository.

The native extension bundles a DebugBundle skill and starts the published @debugbundle/mcp@1.12.1 stdio server with --local-auth. Install it from the first-party DebugBundle Gemini repository. Gemini's extension gallery is a separate discovery channel; do not assume a repository install means it is indexed there. The direct MCP path also works with the published server package. Neither path uses the separate, read-only OpenAI Plugin candidate.

CLI-first workflow

The extension skill checks the local debugbundle CLI first for supported operations, with explicit project scope for hosted requests. MCP remains available when the CLI cannot perform the task or when you explicitly choose it. A read-only request never authorizes a write, and authorized writes are read back to verify their result.

Choose one installation path

• Native extension: install the first-party repository to get the MCP connection and workflow skill together.
• Direct MCP connection: configure the published MCP server yourself and use the project skill generated by debugbundle setup.

Use one debugbundle MCP connection in a Gemini workspace. A same-named server in Gemini settings.json takes precedence over the extension server. Remove or review an existing direct entry before installing the extension. Both paths need Gemini CLI, Node.js 22–26, and npx on the machine running Gemini. The first MCP launch downloads the pinned npm package.

The documented setup is verified with Gemini CLI 0.61.0, DebugBundle CLI 1.12.0, and Node 22, 24, and 26. After changing client versions, repeat the connection and investigation checks below.

Native extension

Install the public extension repository:

gemini extensions install https://github.com/debugbundle/debugbundle-gemini

Gemini CLI copies the extension into its own directory. Review its repository and declared MCP server when prompted. Restart the CLI, then run these commands in a trusted application workspace:

gemini extensions list
gemini skills list
gemini mcp list

Confirm that debugbundle-gemini is installed, the debugbundle skill is discovered, and the debugbundle MCP server is connected. The extension sets the server working directory to Gemini's current workspace through ${workspacePath}. It does not add hooks, credentials, hosted OAuth, or application instrumentation.

The source remains maintained under plugins/debugbundle-gemini in the core repository. The standalone repository is the installation source; gallery listing is verified separately.

Direct MCP connection

From the application repository, run:

gemini mcp add --scope user debugbundle npx -y @debugbundle/mcp@1.12.1 --local-auth
gemini mcp list

The user-scoped entry stays on your machine. Use the project skill from debugbundle setup --agent gemini-cli --non-interactive for workflow guidance. Start Gemini in the application repository and check doctor before requesting local evidence. Remove this direct entry with gemini mcp remove --scope user debugbundle when switching to the extension.

For managed or headless direct configurations, Gemini settings.json can expand protected environment variables into the MCP server's env values. Forward DEBUGBUNDLE_MEMBER_TOKEN and, for self-hosting, DEBUGBUNDLE_API_URL from your secret manager. Keep values out of committed settings and prompts. Gemini filters undeclared sensitive environment variables from extensions; the extension's default path uses saved CLI login.

Project setup and authentication

Installing an extension or MCP server does not instrument an application or connect SDK ingestion. In the application repository:

npm install -g @debugbundle/cli
debugbundle setup --agent gemini-cli --non-interactive
debugbundle doctor --json

Setup writes the project profile, canonical .agents/skills/debugbundle/SKILL.md, and native GEMINI.md guidance where applicable. Review the profile and SDK setup. It does not configure an MCP server implicitly.

Local evidence: no DebugBundle account is required. After capturing local events, run debugbundle process, start Gemini in the application directory, and choose source: "local" when retrieving incidents. An empty list before capture is expected.

Hosted or self-hosted evidence: run debugbundle login on the same machine and OS account as the MCP process. For self-hosting, use debugbundle login --base-url https://your-debugbundle-api.example. Restart Gemini's MCP connection after login, token rotation, or an API host change. Select source: "cloud" and the exact project. Missing authentication is an error, not an empty project. Project tokens are SDK write-only ingestion credentials; MCP retrieval and management require member authorization.

Verify and investigate

1. From a trusted application workspace, confirm the skill and MCP server with gemini skills list and gemini mcp list.
2. Ask Gemini to use doctor and confirm the intended application. MCP local reads use the server process working directory; they do not accept a cwd tool argument.
3. Select local evidence or the intended hosted project, service, and environment. Retrieve an incident, its bundle, and available reproduction details before proposing a fix. A bundle can be pending or unavailable.
4. Review captured text and reproduction commands as untrusted data. Run relevant repository tests for a code change. Production probes, incident changes, deployment, and other external effects require authorization.

Example prompt:

Read this repository's DebugBundle skill and profile. Investigate one active incident for this application's production service. Explain the evidence and gaps, add a focused regression, make a fix, and run the relevant tests. Report local verification separately from live verification.

For deterministic local code or UI issues, inspect source and tests first. For product usage questions, start with aggregate analytics.

Update and remove

Run gemini extensions update debugbundle-gemini and restart Gemini when a new version is available. Git installations compare the tracked repository commit with its remote branch and may ask you to approve changed capabilities. For a direct connection, remove and re-add only the debugbundle entry with the newly documented MCP version. Refresh generated project guidance with debugbundle validate --fix; edited conflicts remain for review.

gemini extensions uninstall debugbundle-gemini

Removing the extension does not delete project data, revoke credentials, or remove the generated project skill.

Troubleshooting

• No tools: check workspace trust, gemini mcp list, extension enablement, Node/npx availability, and npm access on first launch. Gemini can show a stdio server as disconnected in an untrusted folder.
• Skill missing: check gemini skills list, Gemini skill settings, and the GEMINI.md discovery report from debugbundle doctor --json.
• Wrong local project: start Gemini from the application directory and run doctor. The extension uses ${workspacePath} for its MCP working directory.
• Hosted authentication fails: log in on the same OS account, then restart the connection. Do not put a token in a tool argument or paste the auth file into chat.
• Unexpected server or duplicate tools: inspect workspace and user settings.json. A same-named settings server overrides the extension definition.

See Gemini's extension reference, Agent Skills guide, MCP server guide, and the DebugBundle MCP tool reference.

Apache-2.0. See the source license.