{
  "markdown": "# Gemini CLI Self-Command Extension\n\nAn MCP tool that allows the Gemini CLI to send commands to itself, run very long commands in the background and be woken, sleep for a specified amount of time, watch logs and receive notifications, etc by leveraging tmux. After installing the extension you must lauch gemini-cli via tmux using the provided shell script or with something like: **SESSION_NAME=\"gemini-cli\"; tmux new-session -d -s $SESSION_NAME 'gemini'; tmux attach -t $SESSION_NAME**\n\n## Purpose\n\nThis extension enables the Gemini agent to execute CLI commands \"on itself\" by injecting them into its own input stream. This is useful for self-correction, navigation, or triggering other CLI features programmatically.\n\n## How it Works\n\n1.  **Immediate Return:** The tool acknowledges the request and returns immediately to avoid blocking the agent. Each request returns a unique **Request ID** (e.g., `[A1B2]`) which is also included in the final completion notification, allowing the agent to correlate actions with results.\n2.  **Stability Check:** All tools wait for the terminal screen to become stable (no output changes for **10 seconds**) before injecting any keystrokes. This ensures they do not interrupt the agent or the user.\n3.  **Tmux Injection:** It uses `tmux send-keys` to simulate user input in the `gemini-cli` session.\n4.  **Serialized Notifications:** All background notifications are serialized using a file-based lock. This prevents garbled output when multiple tasks (like a long command and a log watcher) complete simultaneously.\n5.  **Monitoring & Resume:** A background worker monitors the terminal output. Once it detects the command has finished (by observing screen stability), it sends a \"Resume\" signal to the agent, ensuring the agent knows when it can proceed.\n\n## Tools\n\n### self_command\nSends a command to the Gemini CLI. It waits for the session to stabilize after the command is sent and then notifies the agent to resume. Returns a unique Request ID.\n\n### gemini_sleep\nSleeps for a specified number of seconds and then sends a wake-up notification to the tmux session. Returns a unique Request ID.\n**Features:**\n- **Recurring Sleep:** Can be set to wake up periodically (min 1 hour interval).\n- **Single Active Sleep:** Enforces a single active sleep policy. If a new sleep is requested, the system keeps the one that ends sooner and cancels the other.\n\n### watch_log\nMonitors a log file and wakes the system up when the file changes or when new content matches a provided regex pattern. Supports a configurable timeout. Returns a unique Request ID.\n\n### cancel_watch\nCancels active log watchers, either globally or for a specific file. Now gracefully handles cases where no matching watchers are found.\n\n### yield_turn\nActs as an immediate interrupt that terminates the agent's current turn by sending `Ctrl-C` and preparing the CLI for subsequent input. Returns a unique Request ID.\n\n**Why it exists:**\nThe Gemini agent is not naturally \"aware\" of background processes or tmux-style key injections. When a command is scheduled (e.g., via the run-long-command extension), the agent needs to stop its current turn to wait for the completion notification. `yield_turn` breaks the execution loop by sending an interrupt signal after a minimal delay (500ms).\n\n**CRITICAL:** This tool MUST be the only action in your turn. Combining it with other tools will cause session state corruption and cancelled commands.\n\n### run_long_command\nExecutes a long-running shell command in the background without blocking the agent. It notifies Gemini upon completion (success or failure) by injecting a message into the tmux session. Returns a unique Request ID.\n\n### send_keys\nSends keystrokes to a specific tmux pane. Useful for interacting with TUI apps, confirming prompts (e.g., 'y/n'), or sending control signals like `Ctrl-C`.\n\n### capture_pane\nCaptures the visible text content of a tmux pane. Useful for checking the status of TUI apps or reading output from a pane that isn't the main agent pane.\n\n### create_pane\nSplits the current window to create a new pane and optionally runs a command in it. Useful for running parallel tasks like servers or watchers while keeping the main terminal free.\n\n### close_pane\nCloses a specific tmux pane. Used to clean up panes created by `create_pane`.\n\n### wait_for_idle\nWaits for the system CPU usage to drop below a specified threshold for a set duration. Useful for waiting for resource-intensive tasks (like compilation) to finish when there is no specific log message to watch.\n\n## Prerequisites\n\n-   **Tmux:** You must run the Gemini CLI inside a tmux session named `gemini-cli`.\n-   **Node.js:** Required to run the MCP server.\n\n## Installation\n\n### Standard Installation (Recommended)\nYou can install this extension directly via the Gemini CLI:\n```bash\ngemini extensions install https://github.com/stevenAthompson/self-command\n```\n\n### Manual Installation\n1.  Clone this repository.\n2.  Install dependencies:\n    ```bash\n    npm install\n    ```\n3.  Build the project:\n    ```bash\n    npm run build\n    ```\n\n## Usage\n\n1.  Start the tmux session using the helper script:\n    ```bash\n    ./gemini_tmux.sh\n    ```\n2.  Inside the session, start Gemini (if not already started).\n3.  Load this MCP server into Gemini.\n4.  Ask Gemini to run a command on itself, e.g., \"Run the 'help' command on yourself\".\n\n## Development\n\n-   **Test:** `npm test`\n-   **Build:** `npm run build`\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
  "bytes": 5558,
  "sha": "59860ca04eb5dfa7ffa0cd714a30b6316d69f5cf572d0be47db52b16810d5f84",
  "repo_slug": "stevenathompson/self-command",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_stevenathompson_self_command_fa315a39/readme"
}