Metadata-Version: 2.4
Name: sage-ai-cli
Version: 1.12.2
Summary: Sage — a local-first AI coding CLI (like Claude Code, using free/open models)
Author: Layne Faler
License: MIT
Project-URL: Repository, https://github.com/laynef/claude-ai-clone
Keywords: ai,cli,llm,coding,local,gemini,gguf,llama
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: prompt-toolkit>=3.0.43
Provides-Extra: local
Requires-Dist: llama-cpp-python>=0.2.90; extra == "local"
Provides-Extra: server
Requires-Dist: fastapi>=0.115.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.30.0; extra == "server"
Requires-Dist: pydantic>=2.9.0; extra == "server"
Requires-Dist: pydantic-settings>=2.5.0; extra == "server"
Provides-Extra: all
Requires-Dist: llama-cpp-python>=0.2.90; extra == "all"
Requires-Dist: fastapi>=0.115.0; extra == "all"
Requires-Dist: uvicorn[standard]>=0.30.0; extra == "all"
Requires-Dist: pydantic>=2.9.0; extra == "all"
Requires-Dist: pydantic-settings>=2.5.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"

# 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 openai-fast     # Fast variant
```

## 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

## Other Commands

```bash
# One-shot question
sage ask "explain quicksort"

# Ask about a file
sage ask -f script.py "what does this do?"

# Pipe input
cat error.log | sage ask "what went wrong?"

# Interactive chat (no file writing)
sage chat

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

## Available Models

### Free API Models (no setup required)
| Model | Provider | Speed |
|-------|----------|-------|
| `openai` | Pollinations (GPT-4o Mini) | Medium |
| `openai-fast` | Pollinations (GPT-4o Mini) | Fast |

### 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
sage config set default_model openai
sage config set temperature 0.1
sage config set max_tokens 4096
```

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)
