sage-ai-cli 1.18.8

Sage — a local-first AI coding CLI (like Claude Code, using free/open models)

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.

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

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

# 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

# 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, then:

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

# 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
• GitHub Repository