@ikyyofc/gemini-cli 2.0.6 → 2.0.7

package/README.md

@@ -3,17 +3,28 @@
 > AI Agent CLI — native function calling · GEMINI.md context · extension system
 
 ```
-   ██████╗ ███████╗███╗   ███╗██╗███╗   ██╗██╗
-  ██╔════╝ ██╔════╝████╗ ████║██║████╗  ██║██║
-  ██║  ███╗█████╗  ██╔████╔██║██║██╔██╗ ██║██║
-  ██║   ██║██╔══╝  ██║╚██╔╝██║██║██║╚██╗██║██║
-  ╚██████╔╝███████╗██║ ╚═╝ ██║██║██║ ╚████║██║
-   ╚═════╝ ╚══════╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═╝
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Gemini CLI  ─  AI Agent  ─  native function calling
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+Gemini CLI adalah asisten terminal bertenaga AI yang menggunakan model Gemini dari Google. CLI ini bukan sekadar antarmuka chat biasa, melainkan sebuah **AI Agent** yang dapat berinteraksi langsung dengan sistem file dan environment lokal Anda menggunakan *native function calling*.
+
 ---
 
-## Instalasi
+## 📚 Dokumentasi Lengkap
+
+Untuk detail lebih lanjut mengenai arsitektur dan fitur spesifik, silakan baca dokumentasi berikut:
+
+- [**Architecture Overview**](./docs/ARCHITECTURE.md) - Penjelasan tentang ReAct loop dan cara kerja agent.
+- [**API Reference**](./docs/API.md) - Referensi fungsi utama (`callGemini`, `chat`).
+- [**Tools (Function Calling)**](./docs/TOOLS.md) - Daftar lengkap tool yang tersedia untuk agent (baca file, jalankan shell, dll).
+- [**Extensions System**](./docs/EXTENSIONS.md) - Cara membuat dan mengelola ekstensi serta custom commands.
+- [**Memory & Context**](./docs/MEMORY.md) - Panduan menggunakan `GEMINI.md` untuk memberikan konteks pada agent.
+
+---
+
+## 🚀 Instalasi
 
 ```bash
 npm install
@@ -23,118 +34,73 @@ npm link    # optional: pakai sebagai `gemini` di terminal
 
 ---
 
-## Penggunaan
+## 💻 Penggunaan
+
+Anda dapat menggunakan Gemini CLI dalam mode interaktif (REPL) atau mode *one-shot* langsung dari terminal.
 
 ```bash
-gemini                                    # interactive agent
-gemini "buatkan REST API di ./api"        # one-shot
-gemini --system "Kamu senior backend engineer"
-gemini --file ./app.js "jelaskan kode ini"
-gemini --yolo "refactor semua file di src/"
-gemini --chat                             # plain chat tanpa tools
+gemini                                    # Masuk ke mode interactive agent
+gemini "buatkan REST API di ./api"        # One-shot task
+gemini --system "Kamu senior backend engineer" # Set system prompt
+gemini --file ./app.js "jelaskan kode ini"     # Lampirkan file
+gemini --yolo "refactor semua file di src/"    # Skip semua konfirmasi tool (HATI-HATI)
+gemini --chat                             # Plain chat tanpa tools (bukan agent)
 ```
 
----
-
-## GEMINI.md — Context Files
+### Interactive Commands
 
-Buat `GEMINI.md` di lokasi berikut (dimuat hierarki, seperti Gemini CLI asli):
+Saat berada di dalam mode interaktif, Anda dapat menggunakan perintah berikut:
 
-| Lokasi | Scope |
-|--------|-------|
-| `~/.gemini/GEMINI.md` | Global semua project |
-| `./GEMINI.md` | Project root (sampai `.git`) |
-
-Support import antar file:
-```md
-@./components/style.md
-@../shared/conventions.md
-```
-
-**Commands:**
 ```
-/memory show          → tampilkan semua context yang dimuat
-/memory reload        → reload dari disk
-/memory add <text>    → append ke ~/.gemini/GEMINI.md
+/agent                 → Toggle agent mode (tools on/off)
+/yolo                  → Skip all tool confirmations
+/file <path>           → Attach file to next message
+/system <text>         → Set system instruction
+/history               → Show conversation turns
+/export <file>         → Export history to JSON
+/cd <path>             → Change working directory
+/cwd                   → Show current working directory
+/new  /clear           → Reset conversation
+/model                 → Show model & config
+/help                  → Show help
+/exit  /quit           → Exit
 ```
 
 ---
 
-## Extensions
-
-Manifest: `~/.gemini/extensions/<name>/gemini-extension.json`
-
-```json
-{
-  "name": "my-ext",
-  "version": "1.0.0",
-  "description": "...",
-  "contextFileName": "GEMINI.md",
-  "enabled": true,
-  "commands": {
-    "do-thing": {
-      "description": "Does a thing",
-      "prompt": "Do this: {{args}}"
-    }
-  }
-}
-```
+## 🧠 Fitur Utama
 
-**Commands:**
-```
-/ext list
-/ext install /path/to/ext
-/ext install https://github.com/user/repo
-/ext uninstall <name>
-/ext enable / disable <name>
-/ext update <name>
-```
-
-Custom commands dipanggil: `/code-reviewer:review ./src/app.js`
+### 1. Native Function Calling (Tools)
+Agent dapat membaca file, menulis file, menjalankan perintah shell, dan mencari file secara mandiri untuk menyelesaikan tugas yang Anda berikan. [Baca selengkapnya](./docs/TOOLS.md).
 
----
+### 2. Hierarchical Context (`GEMINI.md`)
+Anda dapat memberikan instruksi spesifik proyek atau global menggunakan file `GEMINI.md`. Agent akan memuat konteks ini secara otomatis. [Baca selengkapnya](./docs/MEMORY.md).
 
-## Tools (Native Function Calling)
-
-| Tool | Aksi |
-|------|------|
-| `read_file` | Baca file |
-| `write_file` | Tulis/overwrite file |
-| `patch_file` | Edit bagian spesifik |
-| `append_file` | Append ke file |
-| `list_dir` | List direktori |
-| `find_files` | Cari file (glob) |
-| `search_in_files` | Grep dalam file |
-| `run_shell` | Jalankan shell command |
-| `create_dir` | Buat direktori |
-| `delete_file` | Hapus file |
-| `move_file` | Pindah/rename |
-| `get_env` | Info environment |
-| `read_url` | Fetch URL / API |
+### 3. Extension System
+Perluas kemampuan CLI dengan membuat ekstensi yang berisi custom commands dan konteks tambahan. [Baca selengkapnya](./docs/EXTENSIONS.md).
 
 ---
 
-## Struktur
+## 📂 Struktur Direktori
 
 ```
 gemini-cli/
 ├── index.js                   ← CLI entry + REPL + commands
-├── GEMINI.md                  ← Project context (auto-loaded)
 ├── package.json
+├── docs/                      ← Dokumentasi lengkap
 ├── src/
 │   ├── gemini.js              ← API client (native function calling)
 │   ├── tools.js               ← functionDeclarations + executor
 │   ├── agent.js               ← ReAct loop
 │   ├── memory.js              ← GEMINI.md hierarchy loader
 │   ├── extensions.js          ← Extension manager
-│   └── renderer.js            ← Terminal UI + markdown
-└── extensions/
-    └── code-reviewer/
-        ├── gemini-extension.json
-        └── GEMINI.md
-
-~/.gemini/                     ← Global config dir
-├── GEMINI.md
-├── extensions/
-└── commands/
-```
+│   ├── renderer.js            ← Terminal UI + markdown
+│   └── input.js               ← Bracketed paste via Transform stream
+└── utils/
+    └── proxy-manager.js       ← Global proxy manager
+
+~/.gemini/                     ← Global config dir (dibuat otomatis)
+├── GEMINI.md                  ← Global context
+├── extensions/                ← Folder instalasi ekstensi
+└── commands/                  ← Global custom commands
+```

package/docs/API.md

@@ -0,0 +1,37 @@
+# API Reference
+
+The Gemini CLI exposes its core functionality through `src/gemini.js`.
+
+## `callGemini(options)`
+
+The primary function for interacting with the Gemini API, supporting native function calling and multimodal inputs.
+
+### Parameters
+
+An object containing the following properties:
+
+- `messages` (Array): The conversation history. Each message should have a `role` (`user` or `model`) and `parts` (an array of text or function call/response objects).
+- `fileBuffer` (Buffer, optional): A buffer containing a file to be sent as an inline attachment (e.g., an image or document).
+- `tools` (Array, optional): An array of tool declarations. Typically `GEMINI_TOOLS` from `src/tools.js`.
+- `systemInstruction` (String, optional): The system prompt to guide the model's behavior.
+
+### Returns
+
+A Promise that resolves to an object containing:
+
+- `parts`: The response parts from the model (text or function calls).
+- `raw`: The raw response object from the API.
+- `full`: The complete API response data.
+
+## `chat(messages, systemInstruction)`
+
+A simplified wrapper around `callGemini` for plain text chat without tools.
+
+### Parameters
+
+- `messages` (Array): The conversation history.
+- `systemInstruction` (String, optional): The system prompt.
+
+### Returns
+
+A Promise that resolves to the concatenated text response from the model.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,40 @@
+# Architecture Overview
+
+Gemini CLI is built around a ReAct (Reasoning and Acting) agent loop that leverages Gemini's native function calling capabilities.
+
+## Core Components
+
+1. **Agent Loop (`src/agent.js`)**
+   - Implements the ReAct loop.
+   - Sends the conversation history and available tools to the Gemini API.
+   - If the model responds with a `functionCall`, the agent executes the corresponding tool locally.
+   - The result of the tool execution is appended to the conversation history as a `functionResponse`.
+   - This loop continues until the model provides a final text response without any tool calls.
+
+2. **Native Function Calling (`src/gemini.js` & `src/tools.js`)**
+   - The CLI uses Gemini's native `tools` parameter to pass `functionDeclarations`.
+   - `src/tools.js` defines the schema for all available tools (e.g., `read_file`, `run_shell`) using an OpenAPI-subset format.
+   - The `executeTool` function handles the actual execution of these tools on the local system, including prompting the user for confirmation on destructive actions.
+
+3. **Memory & Context (`src/memory.js`)**
+   - Implements a hierarchical context loading system based on `GEMINI.md` files.
+   - Context is loaded globally (`~/.gemini/GEMINI.md`), from extensions, and from the project root up to the current working directory.
+   - Supports recursive imports using `@./path/to/file.md`.
+
+4. **Extension System (`src/extensions.js`)**
+   - Allows extending the CLI's capabilities with custom commands and context.
+   - Extensions are stored in `~/.gemini/extensions/` and defined via a `gemini-extension.json` manifest.
+   - Custom commands can be defined in extensions or globally in `~/.gemini/commands/`.
+
+5. **Terminal UI (`src/renderer.js` & `src/input.js`)**
+   - Handles rendering markdown, syntax highlighting, and tool execution status in the terminal.
+   - `src/input.js` manages user input, including support for bracketed paste to handle multi-line inputs gracefully.
+
+## Data Flow
+
+1. User enters a prompt in the CLI.
+2. The CLI loads context from `GEMINI.md` files and extensions.
+3. The prompt, context, and tool declarations are sent to the Gemini API via `callGemini`.
+4. The model decides whether to respond with text or call a tool.
+5. If a tool is called, `agent.js` executes it via `tools.js` and sends the result back to the model.
+6. Once the model finishes reasoning and acting, the final text response is rendered to the user.

package/docs/EXTENSIONS.md

@@ -0,0 +1,65 @@
+# Extensions System
+
+Gemini CLI supports an extension system that allows you to add custom commands and context to the agent. Extensions are managed in `~/.gemini/extensions/`.
+
+## Extension Structure
+
+An extension is a directory containing at least a `gemini-extension.json` manifest file. It can optionally include a `GEMINI.md` file for context.
+
+```
+~/.gemini/extensions/my-extension/
+├── gemini-extension.json
+└── GEMINI.md
+```
+
+## Manifest (`gemini-extension.json`)
+
+The manifest defines the extension's metadata and custom commands.
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "description": "A sample extension",
+  "contextFileName": "GEMINI.md",
+  "enabled": true,
+  "commands": {
+    "review": {
+      "description": "Review the provided code",
+      "prompt": "Please review the following code and suggest improvements: {{args}}"
+    }
+  }
+}
+```
+
+## Custom Commands
+
+Custom commands defined in the manifest can be invoked in the CLI using the syntax `/extension-name:command-name [args]`.
+
+For example, using the manifest above:
+```bash
+/my-extension:review ./src/app.js
+```
+This will expand to the prompt defined in the manifest, replacing `{{args}}` with `./src/app.js`.
+
+## Managing Extensions
+
+You can manage extensions using the `/ext` command in the interactive CLI:
+
+- `/ext list`: List all installed extensions.
+- `/ext install <path-or-url>`: Install an extension from a local path or a Git repository.
+- `/ext uninstall <name>`: Uninstall an extension.
+- `/ext enable <name>`: Enable an extension.
+- `/ext disable <name>`: Disable an extension.
+- `/ext update <name>`: Update an extension (if installed via Git).
+
+## Global Commands
+
+In addition to extensions, you can define global custom commands in `~/.gemini/commands/<namespace>/<name>.toml`.
+
+Example `~/.gemini/commands/git/commit.toml`:
+```toml
+description = "Generate a commit message"
+prompt = "Generate a concise conventional commit message for the following git diff: {{args}}"
+```
+Usage: `/git:commit`

package/docs/MEMORY.md

@@ -0,0 +1,36 @@
+# Memory & Context (`GEMINI.md`)
+
+Gemini CLI uses a hierarchical context loading system based on `GEMINI.md` files. This allows you to provide persistent instructions, coding conventions, and project-specific knowledge to the AI agent.
+
+## Context Hierarchy
+
+When you start a conversation, the CLI loads context from `GEMINI.md` files in the following order (lowest to highest priority):
+
+1. **Global Context**: `~/.gemini/GEMINI.md`
+   - Use this for global preferences, such as "Always use TypeScript" or "I prefer concise answers."
+2. **Extension Context**: `~/.gemini/extensions/<name>/GEMINI.md`
+   - Extensions can inject their own context when enabled.
+3. **Project Context**: Walk up from the Current Working Directory (CWD) to the project root (defined by the presence of a `.git` folder).
+   - E.g., if you are in `/project/src/components`, it will load `/project/GEMINI.md`, then `/project/src/GEMINI.md`, then `/project/src/components/GEMINI.md`.
+   - This allows you to define project-wide rules at the root, and specific rules for subdirectories.
+
+## Imports
+
+You can modularize your context files using the `@./path/to/file.md` syntax. The CLI will recursively resolve and inline these imports.
+
+Example `GEMINI.md`:
+```markdown
+# Project Context
+This is a React project.
+
+@./docs/conventions.md
+@./docs/architecture.md
+```
+
+## Managing Memory
+
+You can interact with the memory system using the `/memory` command in the interactive CLI:
+
+- `/memory show`: Display all currently loaded context files and their contents.
+- `/memory reload`: Reload the context files from disk (useful if you edited them outside the CLI).
+- `/memory add <text>`: Append text to your global `~/.gemini/GEMINI.md` file.

package/docs/TOOLS.md

@@ -0,0 +1,44 @@
+# Tools (Native Function Calling)
+
+Gemini CLI provides a set of built-in tools that the AI agent can use to interact with your local system. These tools are defined in `src/tools.js` and are passed to the Gemini API as native `functionDeclarations`.
+
+## Available Tools
+
+### File System Operations
+
+- **`read_file`**: Reads the full contents of a file. Returns numbered lines to help the AI reference specific parts of the code.
+  - Parameters: `path` (String)
+- **`write_file`**: Creates or overwrites a file with the provided content. Automatically creates parent directories. *(Requires confirmation)*
+  - Parameters: `path` (String), `content` (String)
+- **`patch_file`**: Replaces a specific unique string in a file with a new string. Safer than rewriting whole files. *(Requires confirmation)*
+  - Parameters: `path` (String), `old_str` (String), `new_str` (String)
+- **`append_file`**: Appends text to the end of an existing file. *(Requires confirmation)*
+  - Parameters: `path` (String), `content` (String)
+- **`delete_file`**: Permanently deletes a file or empty directory. *(Requires confirmation)*
+  - Parameters: `path` (String)
+- **`move_file`**: Moves or renames a file or directory. *(Requires confirmation)*
+  - Parameters: `from` (String), `to` (String)
+
+### Directory & Search Operations
+
+- **`list_dir`**: Lists files and subdirectories in a directory. Excludes `node_modules` and `.git` by default.
+  - Parameters: `path` (String, optional), `show_hidden` (Boolean, optional)
+- **`create_dir`**: Creates a directory and all necessary parent directories (`mkdir -p`). *(Requires confirmation)*
+  - Parameters: `path` (String)
+- **`find_files`**: Finds files matching a name pattern (glob) recursively.
+  - Parameters: `pattern` (String), `dir` (String, optional)
+- **`search_in_files`**: Searches for a text pattern (grep) inside files recursively.
+  - Parameters: `pattern` (String), `dir` (String, optional), `extension` (String, optional), `case_insensitive` (Boolean, optional)
+
+### Execution & Environment
+
+- **`run_shell`**: Executes any shell command (e.g., `npm install`, `git status`, running tests). Returns stdout and stderr. *(Requires confirmation)*
+  - Parameters: `command` (String), `cwd` (String, optional), `timeout` (Number, optional)
+- **`get_env`**: Retrieves information about the current environment (CWD, platform, Node version, Git branch, etc.).
+  - Parameters: None
+- **`read_url`**: Fetches the raw content of a URL (web page, REST API, raw file).
+  - Parameters: `url` (String), `headers` (String, optional)
+
+## Security & Confirmation
+
+Tools marked with *(Requires confirmation)* are considered destructive. When the AI attempts to use one of these tools, the CLI will pause and prompt the user for approval before executing the action. This can be bypassed using the `/yolo` command or the `--yolo` flag.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikyyofc/gemini-cli",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "AI CLI Agent powered by Gemini — your own terminal assistant",
   "type": "module",
   "main": "index.js",