https://github.com/vigyatgoel/ollama-code-cli
Ollama Code CLI is an interactive command-line tool that uses local LLMs via Ollama for coding tasks and advanced tool calling.
https://github.com/vigyatgoel/ollama-code-cli
Last synced: 4 months ago
JSON representation
Ollama Code CLI is an interactive command-line tool that uses local LLMs via Ollama for coding tasks and advanced tool calling.
- Host: GitHub
- URL: https://github.com/vigyatgoel/ollama-code-cli
- Owner: VigyatGoel
- License: mit
- Created: 2025-08-30T09:01:34.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-06T08:33:32.000Z (10 months ago)
- Last Synced: 2025-11-27T17:10:28.402Z (7 months ago)
- Language: Python
- Homepage:
- Size: 119 KB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-software-engineering-tools - ollama code cli - code-cli\] (Vibe Coding)
README
# Ollama Code CLI
[](https://badge.fury.io/py/ollama-code-cli)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
**Ollama Code CLI is an open-source AI agent that brings the power of local LLMs through Ollama, right in your terminal, with advanced tool-calling features.**
---
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Requirements](#requirements)
- [Usage](#usage)
- [Available Tools](#available-tools)
- [Examples](#examples)
- [Interactive Mode](#interactive-mode)
- [Project Structure](#project-structure)
- [Dependencies](#dependencies)
- [Contributing](#contributing)
- [License](#license)
---
## Features
- 🎨 **Elegant CLI Interface:** Rich colors and structured output
- 🤖 **Local AI Power:** Interact with local LLMs through Ollama
- 🛠️ **Tool Calling:** Execute coding-related tools (file operations, code execution, etc.)
- 🔒 **Permission Prompts:** Safety prompts before executing potentially dangerous operations
- 💬 **Interactive Mode:** Maintain conversation context for multi-turn interactions
- 📝 **Markdown Support:** Elegantly formatted responses with syntax highlighting
- 📋 **Structured Output:** Clear panels and tables for tool calls and results
---
## Installation
First, install a compatible model in Ollama:
```bash
# Choose one of these models:
ollama pull qwen3:4b
ollama pull qwen2.5:3b
```
Then install the CLI:
```bash
pip install ollama-code-cli
```
### macOS Installation Note
If you see an error like `"externally-managed-environment"` when using `pip3 install`, this is because modern macOS and Homebrew Python prevent global package installation. Use one of these methods instead:
**Option 1: Use pipx**
```bash
brew install pipx
pipx ensurepath
pipx install ollama-code-cli
```
**Option 2: Use a virtual environment**
```bash
python3 -m venv ~/.venvs/ollama-code-cli
source ~/.venvs/ollama-code-cli/bin/activate
pip install ollama-code-cli
```
**Option 3: Use uv (Fast Python package manager)**
```bash
brew install uv
uv tool install ollama-code-cli
```
---
## Requirements
- Python 3.13+
- Ollama installed and running
- An Ollama model that supports tool calling (e.g., Qwen3, Qwen2.5, etc.)
---
## Usage
Start an interactive session:
```bash
ollama-code-cli --model qwen3:4b
```
Run a single command:
```bash
ollama-code-cli "Create a Python function to calculate factorial"
```
Use a specific model:
```bash
ollama-code-cli --model qwen3:4b "Explain how async/await works in Python"
```
Disable permission prompts (use with caution):
```bash
ollama-code-cli --no-permission "Create and run a Python script"
```
---
## Security Features
The CLI includes built-in security features to protect against potentially dangerous operations:
### Permission Prompts
By default, the CLI will ask for your permission before executing potentially dangerous operations such as:
- Writing or modifying files
- Executing code
- Running shell commands
- Running Python files
### Safe Operations
These operations are considered safe and don't require permission:
- Reading files
- Listing directory contents
### Bypassing Permission Prompts
You can disable permission prompts using the `--no-permission` flag, but this should be used with caution:
```bash
ollama-code-cli --no-permission "Your prompt here"
```
**Warning:** Disabling permission prompts allows the AI to execute operations without user confirmation. Only use this in trusted environments.
---
## Available Tools
- `read_file`: Read the contents of a file
- `write_file`: Write content to a file
- `execute_code`: Execute code in a subprocess
- `list_files`: List files in a directory
- `run_command`: Run a shell command
---
## Examples
**1. Create a Python script and save it to a file:**
```bash
ollama-code-cli "Create a Python script that calculates factorial and save it to a file named factorial.py"
```
**2. Read a file and explain its contents:**
```bash
ollama-code-cli "Read the contents of main.py and explain what it does"
```
**3. Execute a shell command:**
```bash
ollama-code-cli "List all files in the current directory"
```
---
## Interactive Mode
Launch the interactive mode for a conversational experience:
```bash
ollama-code-cli
```
In interactive mode, you can:
- Have multi-turn conversations with the AI
- See elegantly formatted responses with Markdown support
- Watch tool calls and results in real-time with visual panels
- Clear conversation history with the `clear` command
- Exit gracefully with the `exit` command
---
## Project Structure
```
ollama-code-cli/
├── ollama_code_cli/
│ ├── __init__.py
│ ├── cli/
│ │ ├── __init__.py
│ │ └── cli.py # Main CLI interface
│ ├── tools/
│ │ ├── __init__.py
│ │ └── tool_manager.py # Tool implementations
├── pyproject.toml # Project configuration
├── LICENSE
└── README.md
```
---
## Dependencies
- [Rich](https://github.com/Textualize/rich) — Elegant terminal formatting
- [Click](https://click.palletsprojects.com/) — Command-line interface
- [Ollama Python Client](https://github.com/ollama/ollama-python) — Ollama integration
---
## Contributing
Contributions are welcome! Please open an issue or submit a pull request for any improvements, bug fixes, or suggestions.
---
## License
This project is licensed under the [MIT License](LICENSE).