hooklog
Logs all Gemini CLI hook events to a file for debugging and analysis.
Open source Open in the app JSON README (API)
About
Logs all Gemini CLI hook events to a file for debugging and analysis.
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- sandipchitale
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Last push
- 2026-02-17T05:10:02Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
sandipchitale/hooklog
README
# Gemini CLI Hooks Logger
A comprehensive logging extension for the Gemini CLI that captures and logs all hook events for debugging and analysis purposes.
## Overview
This extension integrates with the Gemini CLI hook system to provide visibility into the CLI's internal operations. It intercepts every hook event, logs the details to a file, and facilitates easy inspection by automatically opening the log file in VS Code upon session start.
## Features
- **Complete Hook Coverage**: Logs events for all major hooks including `SessionStart`, `BeforeModel`, `AfterModel`, `SessionEnd`, agent interactions, and tool usage.
- **Structured Logging**: Stores logs as JSON objects with timestamps and session IDs for easy parsing.
- **Automatic Debugging**: Automatically launches a new VS Code window pointing to the log directory and opens the current session's log file when a new session starts.
- **Non-Intrusive**: Designed to work transparently alongside your main CLI operations, passing through data so the CLI continues to function normally.
## Installation
1. Ensure you have the Gemini CLI installed.
2. Place this directory `gemini-cli-hooklog` (containing `gemini-extension.json`) into your Gemini CLI extensions directory (e.g., `~/.gemini/extensions/` or wherever your CLI is configured to look for extensions).
## How it Works
The extension uses a configuration file `hooks/hooks.json` to map every hook event to a single handler script `scripts/hooklog.ts`.
When a hook is triggered:
1. The CLI executes `node scripts/hooklog.ts`.
2. The script reads the hook event data (JSON) from `stdin`.
3. It appends a formatted log entry to a file in the system's temporary directory:
- Linux/Mac: `/tmp/gemini-cli-hooks-log/<session-id>.log` (or similar depending on `os.tmpdir()`)
- Windows: `%TEMP%\gemini-cli-hooks-log\<session-id>.log`
4. If the event is `SessionStart`, it attempts to open the log folder and file in VS Code using the `code` command.
5. Finally, it echoes the input JSON to `stdout` to ensure the hook chain continues without interruption.
## Configuration
### Enable/Disable Logging
You can enable or disable logging via the extension settings.
- **Setting**: `Enable Logging`
- **Environment Variable**: `GEMINI_HOOKLOG_ENABLE`
- **Default**: `true` (Enabled)
- **Description**: Whether to enable logging of hook events. Set to `false` to disable logging.
### Example Usage
```
> gemini extensions config hooklog
Loaded cached credentials.
Configuring settings for "hooklog"...
✔ Setting "Enable Logging" (GEMINI_HOOKLOG_ENABLE) is already set. Overwrite? … yes
✔ Enable Logging
Whether to enable logging of hook events. … false
```
The `hooks/hooks.json` file defines which hooks are intercepted. Currently, it is configured to intercept:
- `SessionStart`
- `BeforeModel` / `AfterModel`
- `SessionEnd`
- `BeforeAgent` / `AfterAgent`
- `BeforeToolSelection`
- `BeforeTool` / `AfterTool`
- `PreCompress`
- `Notification`
## Prerequisites
- **Node.js**: The script is executed using `node`.
- **TypeScript Support**: Since the script is written in TypeScript (`.ts`), you may need a runtime that supports TypeScript directly (like `ts-node` or `bun`) or you might need to compile the script to JavaScript if running with standard Node.js.
- _Note: The current `hooks.json` configuration invokes `node`. Ensure your environment supports running the `.ts` file or update the command/file extension accordingly._
- **VS Code**: For the automatic file opening feature to work, the `code` command must be available in your implementation environment's PATH.
## License
MIT