This is a simple proof-of-concept how the functionality of google gemini-cli could be implemented in python. The interactive command-line interface (CLI) acts as an agentic AI assistant, powered by Google's Gemini models. It leverages an OAuth2 flow to securely authenticate with Google services and uses a suite of tools to understand and interact with your local development environment. The agent is capable of understanding natural language commands, executing shell commands, reading and writing files, and searching through a codebase to answer questions or perform tasks.
-
Agentic Architecture:
- Multi-Step Task Execution: The agent can autonomously perform complex tasks that require multiple tool calls and reasoning steps without needing manual intervention for each step.
- Interactive REPL & Non-Interactive Mode: Use it in a continuous, conversational REPL shell or pass a prompt directly from the command line for single-shot execution.
- Session Persistence: Automatically saves your conversation state, allowing you to resume your session later. Includes a
/reset
command to start fresh.
-
Comprehensive Tool Suite: The agent is equipped with a set of tools to interact with your environment:
- Code Navigation:
list_directory
,glob
, andsearch_file_content
(usinggit grep
) to understand your codebase. - File Operations:
read_file
,write_file
, andreplace_in_file
for targeted code edits. - System Execution: A
shell
tool to run commands, linters, or tests. - Knowledge & Memory: Built-in
Google Search
for up-to-date information and asave_memory
tool to retain facts across sessions in a globalGEMINI.md
file.
- Code Navigation:
-
Robust Safety Mechanisms:
- User Confirmation: Prompts for user approval before any potentially destructive action (e.g., executing shell commands, overwriting files, or making edits).
- Diff Previews: Before applying code changes with
replace_in_file
, the agent shows you a git-style diff of the proposed modifications. - Automatic Project Snapshots: Before making any changes, the agent uses a hidden, shadow git repository to automatically create a snapshot of your project, giving you a safety net.
- Scoped File Access: Intelligently ignores files specified in your
.gitignore
and.geminiignore
files.
-
Resilience & Intelligence:
- API Error Handling: Features automatic retries with exponential backoff to gracefully handle transient API or network issues.
- Rate Limit Fallback: To ensure high availability, the agent will automatically and temporarily switch from
gemini-2.5-pro
to the fastergemini-2.5-flash
model if it detects persistent rate-limiting.
-
Flexible Configuration:
- Load settings from command-line flags,
.env
files, a workspace.gemini/settings.json
, and a global~/.gemini/settings.json
. - Toggle verbose debug logging on the fly with a
--debug
flag or a/debug
REPL command.
- Load settings from command-line flags,
Tool | Description | Confirmation? |
---|---|---|
shell |
Executes a shell command in the project directory. | Yes |
write_file |
Writes content to a file, overwriting it if it exists. | Yes |
replace_in_file |
Replaces a specific string in a file. | Yes (with Diff) |
save_memory |
Saves a fact to a global long-term memory file. | Yes |
list_directory |
Lists files and subdirectories, respecting ignore rules. | No |
glob |
Finds files matching a glob pattern (e.g., src/**/*.py ). |
No |
search_file_content |
Searches for a regex pattern in all files using git grep . |
No |
read_file |
Reads the content of a specified file. | No |
Google Search |
Performs a web search for current events or information. | No |
-
Clone the Repository:
git clone https://github.com/CrispStrobe/gemini-cli-py/ cd gemini-cli-py
-
Install Dependencies: This project requires Python 3.11+ and a few external libraries.
pip install httpx "google-auth-oauthlib>=1.2.0" pathspec python-dotenv
-
Environment Configuration (Optional): If you are using an Enterprise account, you may need to specify your Google Cloud Project ID. You can do this by creating a
.env
file in the project root:# .env GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
Run the client from your terminal.
To start the interactive shell, simply run the script:
python ./main.py
The application will guide you through a one-time browser-based authentication flow. After that, you'll be dropped into the REPL, ready to chat.
Example Session:
> use the shell tool to list files in the current directory
--- Gemini ---
[AGENT] Calling Tool: shell with args: {'command': 'ls'}
[AGENT] Got Result from shell: {'stdout': 'config.py\ngemini_client.py\nmain.py...', 'stderr': '', 'returncode': 0}
OK. I see the following files and directories: `config.py`, `gemini_client.py`, `main.py`, `services`, `tools`, and `utils`.
What would you like to do next?
----------------
> find all python files
--- Gemini ---
[AGENT] Calling Tool: glob with args: {'pattern': '**/*.py'}
[AGENT] Got Result from glob: {'files': ['main.py', 'tools/core_tools.py', ...]}
I found the following Python files: `main.py`, `tools/core_tools.py`, `config.py`, `gemini_client.py`, and more.
Let me know if you need anything else.
----------------
To exit the session, type quit
or exit
and press Enter.
You can also pass an initial prompt directly from the command line for a single-shot execution.
python ./main.py "search for 'class GeminiClient' in all python files"