From 4599c8e9849748983f5aca1c373ada02f80987f5 Mon Sep 17 00:00:00 2001 From: Gaurav Ghosh Date: Wed, 8 Apr 2026 10:11:55 -0700 Subject: [PATCH] docs(skills): add debug-cli skill and update code-reviewer to reference it --- .gemini/skills/code-reviewer/SKILL.md | 2 + .gemini/skills/debug-cli/SKILL.md | 96 +++++++++++++++++++++++++++ 2 files changed, 98 insertions(+) create mode 100644 .gemini/skills/debug-cli/SKILL.md diff --git a/.gemini/skills/code-reviewer/SKILL.md b/.gemini/skills/code-reviewer/SKILL.md index 37b7c2e1c3..b5f54a84a4 100644 --- a/.gemini/skills/code-reviewer/SKILL.md +++ b/.gemini/skills/code-reviewer/SKILL.md @@ -28,6 +28,7 @@ This skill guides the agent in conducting professional and thorough code reviews npm run preflight ``` 3. **Context**: Read the PR description and any existing comments to understand the goal and history. +4. **Local Verification**: If reviewing a fix or feature for the Gemini CLI itself, activate the `debug-cli` skill to build and interactively test the changes locally using `tmux`. #### For Local Changes: 1. **Identify Changes**: @@ -45,6 +46,7 @@ Analyze the code changes based on the following pillars: * **Security**: Are there any potential security vulnerabilities or insecure coding practices? * **Edge Cases and Error Handling**: Does the code appropriately handle edge cases and potential errors? * **Testability**: Is the new or modified code adequately covered by tests (even if preflight checks pass)? Suggest additional test cases that would improve coverage or robustness. +* **Interactive Verification**: If the changes affect the Gemini CLI behavior or TUI, use the `debug-cli` skill to manually verify the UI/UX or behavioral changes. ### 4. Provide Feedback diff --git a/.gemini/skills/debug-cli/SKILL.md b/.gemini/skills/debug-cli/SKILL.md new file mode 100644 index 0000000000..f6221d24e7 --- /dev/null +++ b/.gemini/skills/debug-cli/SKILL.md @@ -0,0 +1,96 @@ +--- +name: debug-cli +description: Instructions for running and debugging the Gemini CLI locally from source. Use this when asked to diagnose issues or run the gemini cli application. +--- + +# Debug CLI + +This skill provides instructions for the agent to run the Gemini CLI locally built from source to diagnose issues. **Always reproduce the issue interactively first** — before analyzing source code, running unit tests, or attempting fixes. + +## Workflow + +### 1. Understand the Issue + +- **Gather Context:** Fetch and read the GitHub issue description (if applicable) or the user's report. Identify the delta between expected and observed behavior. +- **Consult Documentation:** Use the `cli_help` subagent to clarify intended CLI behavior, command usage, or configuration schemas. For example: `@cli_help "how does proxy configuration work?"`. +- **Deep Dive:** If the documentation isn't enough, use the `codebase_investigator` subagent to analyze the underlying logic, identify relevant files, and map dependencies related to the issue. +- **Live Exploration:** Depending on the exact problem you're debugging, you might have to play with the `/settings` command or other application commands in a live session. +- **Smart Agent Advantage:** Since the Gemini CLI is a smart agent, you can always ask the CLI itself for help figuring out how it works or how to use a specific feature! + +### 2. Build from Source + +Always start by cleaning, building, and bundling the source code to ensure you are running the latest version: + +```bash +npm run clean && npm run build && npm run bundle +``` + +The application can then be started via `./bundle/gemini.js`. + +### 3. Setup Test Directory + +Before running the CLI, create a temporary test directory and configure it with the appropriate files. This ensures the CLI runs with the correct settings for the feature being tested. + +```bash +mkdir -p /path/to/test-dir/.gemini +``` + +Create a `.gemini/settings.json` in that directory with any settings needed for the test. For example, to allowlist domains for the browser agent: + +```json +{ + "agents": { + "browser": { + "allowedDomains": ["*.example.com", "example.com"] + } + } +} +``` + +You may also need `.gemini/keybindings.json`, `GEMINI.md`, and any test project files depending on what you're testing. + +### 4. Launch with tmux + +Always run the Gemini CLI application using `tmux`. This is essential because the application is a complex TUI (Terminal User Interface). `tmux` commands make it easy to read the screen state, send programmatic inputs, and interact with the TUI in a robust way. + +Launch the CLI from within the test directory so it picks up the local settings: + +```bash +cd /path/to/test-dir +/absolute/path/to/bundle/gemini.js [flags] +``` + +### 5. Interact and Reproduce + +Use `tmux send-keys` to send text and keypresses, and `tmux capture-pane` to read the screen. + +#### Submitting Prompts (Paste-Injection Protection) + +The CLI has paste-injection protection. You **must** split text entry and the Enter keypress into separate steps: + +1. **Send the prompt text** (without pressing Enter). +2. **Wait briefly** (~1 second) to let the CLI process the pasted text. +3. **Send only the Enter key** to submit. + +Sending text and Enter together in one command will be rejected by the paste-injection guard. + +#### Authentication + +If the app presents an authentication screen: +- Select the option to authenticate with a **Gemini API key**. +- The key should be prepopulated automatically. Otherwise if a `.env` file is available copy it inside the test directory. + +### 6. Document Results + +- Record observed vs. expected behavior. +- Note any error messages or visual glitches. + +### 7. Fix and Verify (if applicable) + +- Only after confirming the repro, investigate source code and implement a fix. +- Rebuild (`npm run build && npm run bundle`), re-launch, and verify through the interactive flow (Steps 4–5). + +### 8. Cleanup + +- Kill remaining background processes (tmux sessions, etc.). +- Remove the tmp test directory if no longer needed.