# Sage AI CLI

**A free, local-first AI coding agent for your terminal.** Like Claude Code, but using free and open models -- no API key required.

[![PyPI](https://img.shields.io/pypi/v/sage-ai-cli)](https://pypi.org/project/sage-ai-cli/)
[![Python](https://img.shields.io/pypi/pyversions/sage-ai-cli)](https://pypi.org/project/sage-ai-cli/)
[![License](https://img.shields.io/pypi/l/sage-ai-cli)](https://github.com/laynef/claude-ai-clone)

```
pip install sage-ai-cli
sage run
```

## What Sage Does

Sage is an autonomous coding agent that runs in your terminal. It:

- **Plans** your task, breaking it into concrete steps
- **Reads** your codebase to understand the project structure
- **Writes** code using TDD -- tests first, then implementation
- **Runs** tests automatically and fixes failures
- **Iterates** until the task is complete

All using free AI models -- no API keys, no subscriptions, no cloud dependency.

## Quick Start

```bash
# Install
pip install sage-ai-cli

# Start the interactive agent
sage run

# Or use a specific model
sage run --model openai          # Free GPT-4o Mini via Pollinations
sage run --model qwen            # Qwen model via Pollinations
```

## Download Local Models (Optional)

Run AI completely offline with local GGUF models:

```bash
# See available models
sage pull --list

# Download recommended models
sage pull --recommended

# Download a specific model
sage pull qwen2.5-coder-3b
sage pull deepseek-r1-7b

# Run with a local model
sage run --model llama_cpp:qwen2.5-coder-3b
```

Requires the `local` extra: `pip install sage-ai-cli[local]`

## Features

### Autonomous Agent Loop
Sage doesn't just generate code -- it executes a full agent loop:
1. Understands your request
2. Explores your codebase (READ/SEARCH tools)
3. Writes tests first (TDD)
4. Implements the solution
5. Runs tests and auto-fixes failures
6. Repeats until everything passes

### Smart Context
- Scans your project directory on startup
- Understands your tech stack, dependencies, and code patterns
- Uses relative paths from your project root

### Interactive Commands
| Command | Description |
|---------|-------------|
| `/help` | Show all commands |
| `/models` | List available AI models |
| `/model <id>` | Switch to a different model |
| `/think <task>` | Force step-by-step planning |
| `/read <file>` | Read a file into context |
| `/test [cmd]` | Run tests (default: pytest) |
| `/prompts` | Browse and reuse previous prompts |
| `/files` | Show all files written this session |
| `/undo` | Delete last written files |
| `/compact` | Trim conversation to free context |
| `/clear` | Clear conversation history |
| `!<command>` | Run a shell command |
| `"""..."""` | Multi-line input |

### Prompt History
Sage remembers your prompts across sessions. Use arrow keys (up/down) to cycle through previous prompts, or `/prompts` to browse and reuse them.

### Model Persistence
Sage remembers your last-used model per project directory. Next time you run `sage run`, it automatically loads the same model.

### Auto-Fix with Intelligence
When tests fail, Sage doesn't just blindly retry. It:
- Detects when it's stuck in a loop (repetition detection)
- Discovers available project modules to fix import errors
- Trims context to avoid overflow on retries
- Cleans up broken files it created

## Start Chatting

```bash
# Start the interactive agent
sage run

# Or use a specific model
sage run --model openai

# Show/change config
sage config show
sage config set default_model openai
```

## Available Models

### Remote API models (optional API keys)
Use `sage models` and configure providers under **Configuration** below (Groq, OpenRouter, Gemini, DeepSeek, etc.). Sage focuses on **local** Ollama and GGUF by default.

### Ollama Models (190+ models, install once)
Install [Ollama](https://ollama.com), then:

```bash
# Browse all available models
sage models --ollama

# Filter by category
sage models --ollama -c coding
sage models --ollama -c reasoning

# Pull a model
sage pull qwen3
sage pull deepseek-r1
sage pull devstral

# Run with it
sage run --model ollama:qwen3
```

**Top picks:**
| Model | Params | Best For |
|-------|--------|----------|
| `qwen2.5-coder` | 0.5b-32b | Code generation |
| `qwen3` | 0.6b-235b | General + coding |
| `deepseek-r1` | 1.5b-671b | Reasoning + code |
| `devstral` | 24b | Coding agents |
| `gemma4` | e2b-31b | Frontier performance |
| `mistral-small` | 22b-24b | Fast, balanced |

### GGUF Models (download once, run offline without Ollama)
| Model | Size | Best For |
|-------|------|----------|
| `qwen2.5-coder-3b` | ~2 GB | Code generation |
| `deepseek-r1-7b` | ~4.5 GB | Reasoning + code |
| `llama3.2-3b` | ~2 GB | General tasks |
| `mistral-7b` | ~4.5 GB | General + code |

Run `sage pull --list` for the full catalog of 207 models.

## Configuration

Config is stored in `~/.sage/config.json`:

```bash
# View config
sage config show

# Set values
sage config set default_model openai
sage config set temperature 0.7          # 0.0-2.0
sage config set max_tokens 16384

# Set API keys for premium providers
sage config set api_keys.gemini YOUR_KEY
sage config set api_keys.groq YOUR_KEY
sage config set api_keys.openrouter YOUR_KEY
```

### Environment Variables

All settings can be overridden via environment variables:

| Variable | Description |
|----------|-------------|
| `SAGE_DEFAULT_MODEL` | Override default model (e.g. "gemini:gemini-2.0-flash") |
| `SAGE_TEMPERATURE` | Default temperature (0.0-2.0) |
| `SAGE_MAX_TOKENS` | Default max output tokens |
| `SAGE_GEMINI_API_KEY` | Google Gemini API key |
| `SAGE_GROQ_API_KEY` | Groq API key (free: console.groq.com) |
| `SAGE_OPENROUTER_API_KEY` | OpenRouter API key (free models available) |
| `SAGE_CEREBRAS_API_KEY` | Cerebras API key (free: cloud.cerebras.ai) |
| `SAGE_SAMBANOVA_API_KEY` | SambaNova API key (free: cloud.sambanova.ai) |
| `SAGE_TOGETHER_API_KEY` | Together AI API key (free tier) |
| `SAGE_MISTRAL_API_KEY` | Mistral API key (free: console.mistral.ai) |
| `SAGE_COHERE_API_KEY` | Cohere API key (free: dashboard.cohere.com) |
| `SAGE_DEEPSEEK_API_KEY` | DeepSeek API key (cheap: platform.deepseek.com) |
| `GITHUB_TOKEN` | GitHub token for GitHub Models (free) |

Project-specific state (last model, prompt history) is stored in `.sage/` in your project directory.

## Requirements

- Python 3.11+
- For local models: `pip install sage-ai-cli[local]` (adds llama-cpp-python)

## Privacy

- No telemetry or data collection
- Free API models use Pollinations.ai (no API key needed)
- Local models run 100% offline after download
- Prompt history is stored locally in your project's `.sage/` directory

## License

MIT

## Links

- [PyPI Package](https://pypi.org/project/sage-ai-cli/)
- [GitHub Repository](https://github.com/laynef/claude-ai-clone)
