内容
> **Status:** maintenance only. No new general-agent surface.
<div align="center">
# Sage 🦀
**Rust-native code agent in a single binary**
Open-source software engineering agent CLI.<br/>
Local startup benchmark • Single binary • Works offline with Ollama
[](https://www.rust-lang.org/)
[](LICENSE)
[](https://github.com/majiayu000/sage/actions)
[](https://github.com/majiayu000/sage/releases)
[Installation](#-quick-install) • [Quick start](#-quick-start) • [Configuration](docs/user-guide/configuration.md) • [Documentation](docs/README.md) • [Contributing](CONTRIBUTING.md)
</div>
---
<!-- Demo GIF placeholder - record with: vhs demo/demo.tape -->
<!--
<div align="center">
<img src="demo/demo.gif" alt="Sage Demo" width="800"/>
</div>
-->
## Choose a Sage workflow
Sage Agent is the Rust coding-agent CLI distributed as `sage-cli`; the command
is `sage`. This repository is in maintenance-only mode. Evaluate its shipped
workflows and [limitations](#limitations) before adopting it.
| Your task | Start here | What to expect |
|---|---|---|
| Explore an unfamiliar checkout | `sage "Explain the project structure before changing files"` | Interactive task in the current workspace. Review tool requests. |
| Run a bounded one-shot task | `sage -p "Explain this code" --max-steps 5` | Print mode exits without an interactive prompt; the step limit is not a cost limit. |
| Return to previous work | `sage -c` or `sage -r SESSION_ID` | Continue the latest session or select a specific saved session. |
| Use a local model | [Ollama configuration](docs/user-guide/configuration.md) | Requires a running local Ollama service and an installed model; cloud routes require network access and credentials. |
This table describes Sage's own command paths. Startup time, binary size and
model quality depend on the build, machine and provider; there is no controlled
cross-product benchmark here.
## 🚀 Quick Install
**macOS / Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/majiayu000/sage/main/install.sh | bash
```
**Cargo (Sage CLI):**
```bash
cargo install sage-cli
```
**Homebrew:**
```bash
brew install majiayu000/sage/sage
```
## Release Status
- Latest verified GitHub release: [`v0.13.57`](https://github.com/majiayu000/sage/releases/tag/v0.13.57), published on 2026-04-30.
- GitHub release archives are the primary binary distribution path for macOS and Linux.
- Native Windows prebuilt release archives are not currently published; use WSL2, source builds, or `cargo install sage-cli`.
- Cargo installs use the `sage-cli` package (`cargo install sage-cli`); the root workspace package named `sage` is private and is not the CLI package on crates.io.
- Homebrew installs use the `majiayu000/sage` tap.
## ⚡ Quick Start
```bash
# Interactive mode (default)
sage
# Execute task interactively
sage "Create a Python script that fetches GitHub trending repos"
# Print mode - execute and exit (non-interactive)
sage -p "Explain this code"
# Continue most recent session
sage -c
# Resume specific session
sage -r <session-id>
```
### Check setup before the first task
```bash
sage --version
sage --help
sage config init
sage config validate
sage doctor
```
Run these in the intended checkout. `config init` creates the default
`sage_config.json`; configure the selected provider using the
[configuration guide](docs/user-guide/configuration.md), then validate it.
Diagnostic output can contain environment details: redact credentials and
private project data before sharing it in an issue.
### Task and session questions
- **Does `-p` make file access read-only?** No. It selects non-interactive
execution. Sage tools can edit files and run commands; use an appropriate
checkout and review the result.
- **Do I use `sage run` or `sage interactive`?** The current top-level interface
is `sage "task"`, `sage -p "task"`, or plain `sage`. Follow `sage --help` for
the installed version if an older guide differs.
- **How do I continue after restarting the terminal?** Use `sage -c` for the
most recent session or `sage -r SESSION_ID` for a known session. These flags
are alternatives and cannot be combined.
- **Is the whole agent offline when using Ollama?** Model inference can be
local once the model is installed. Web and network-dependent tools still
require connectivity; see the limitations below.
## Limitations
- Sage can edit files and run shell commands in the current workspace; review tool requests and run in a trusted checkout.
- Cloud LLM providers require user-supplied API keys. Only Ollama-backed workflows are designed for offline use.
- Web, browser, MCP, and model-list features depend on local services or network availability and may fail when those dependencies are unavailable.
- Startup benchmark numbers measure local process startup only; they do not measure model latency, task quality, or end-to-end coding speed.
- Provider support is limited to the shipped provider set and documented OpenAI-compatible routes.
## ✨ Features
### 🚀 Performance
- **Fast startup path** - Rust-native binary with a local benchmark script for verification
- **Single ~15MB binary** - No dependencies, instant install
- **Efficient memory** - Low footprint, handles large codebases
### 🤖 Multi-LLM Support
- **Anthropic** - Claude-compatible models
- **OpenAI** - GPT-compatible models
- **Google** - Gemini-compatible models
- **Z.AI** - GLM-5.1 and GLM-5
- **Moonshot AI** - Kimi-compatible models
- **Ollama** - Llama, Mistral, CodeLlama (offline)
- **Azure OpenAI** - Enterprise deployments
- **OpenRouter** - Access 100+ models
- **Doubao** - ByteDance models
- **GLM** - Zhipu AI models
### 🛠️ 40+ Built-in Tools
| Category | Tools |
|----------|-------|
| **File Ops** | Read, Write, Edit, Glob, Grep, NotebookEdit |
| **Shell** | Bash, KillShell, Task, TaskOutput |
| **Web** | WebSearch, WebFetch, Browser |
| **Planning** | TodoWrite, EnterPlanMode, ExitPlanMode |
| **Git** | Full Git integration |
### 🧠 Advanced Features
- **Memory System** - Learns your coding patterns across sessions
- **Checkpoints** - Save and restore agent state
- **Trajectory Recording** - Full execution history for debugging
- **MCP Protocol** - Extend with Model Context Protocol servers
- **Plugin System** - Custom tool development
### 💬 Claude Code Compatible
- **16+ Slash Commands** - `/resume`, `/undo`, `/cost`, `/plan`, `/compact`, `/title`, etc.
- **Session Resume** - Continue where you left off (`sage -c` or `sage -r <id>`)
- **Interactive Mode** - Multi-turn conversations
- **File Change Tracking** - Built-in undo support
## 📖 Usage
### Interactive Mode
```bash
# Start interactive session
sage
# Or with initial task
sage "Create a REST API with user authentication"
```
```
> Create a REST API with user authentication
[Sage creates files, runs commands, shows progress...]
> /cost
┌─────────────────────────────────┐
│ Session Cost & Usage │
├─────────────────────────────────┤
│ Input tokens: 12,450 │
│ Output tokens: 3,200 │
│ Total cost: $0.047 │
└─────────────────────────────────┘
> /resume
[Shows list of previous sessions...]
To resume: sage -r <session-id>
```
### Print Mode (One-Shot)
```bash
# Execute task and exit (non-interactive)
sage -p "Add error handling to main.rs"
# With maximum steps
sage --max-steps 30 -p "Refactor the auth module"
```
### Session Management
```bash
# Continue most recent session
sage -c
# Resume specific session by ID
sage -r abc123
```
### Slash Commands
| Command | Description |
|---------|-------------|
| `/help` | Show help information |
| `/clear` | Clear conversation history |
| `/compact` | Summarize and compact context |
| `/resume [id]` | Resume previous session |
| `/cost` | Show token usage and cost |
| `/undo [msg-id]` | Undo file changes |
| `/plan [open\|clear]` | View/manage execution plan |
| `/checkpoint [name]` | Save current state |
| `/restore [id]` | Restore to checkpoint |
| `/context` | Show context usage |
| `/status` | Show agent status |
| `/tasks` | List background tasks |
| `/commands` | List all slash commands |
| `/title <title>` | Set session title |
| `/init` | Initialize Sage in project |
| `/config` | Manage configuration |
| `/login` | Configure API key for provider |
| `/logout` | Clear stored credentials |
#### Login/Logout Demo
<div align="center">
<img src="docs/images/login-command.png" alt="Login Command Demo" width="600"/>
</div>
## ⚙️ Configuration
Create `sage_config.json` or use environment variables:
```json
{
"default_provider": "anthropic",
"model_providers": {
"anthropic": {
"model": "claude-opus-4-7",
"api_key": "${ANTHROPIC_API_KEY}",
"enable_prompt_caching": true
},
"zai": {
"model": "glm-5.1",
"api_key": "${ZAI_API_KEY}",
"base_url": "https://api.z.ai/api/paas/v4"
},
"moonshot": {
"model": "kimi-k2.6",
"api_key": "${MOONSHOT_API_KEY}",
"base_url": "https://api.moonshot.ai/v1"
},
"ollama": {
"model": "codellama",
"base_url": "http://localhost:11434"
}
},
"max_steps": 20,
"memory": {
"enabled": false,
"storage_path": ".sage/memory/agent-memory.json"
},
"working_directory": "."
}
```
Cross-session memory is opt-in. Set `memory.enabled` to `true` to inject bounded,
redacted project memories and learning patterns into future prompts.
### Environment Variables
```bash
# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export ZAI_API_KEY="..."
export MOONSHOT_API_KEY="sk-..."
# Configuration
export SAGE_DEFAULT_PROVIDER="anthropic"
export SAGE_MAX_STEPS="30"
```
## 📦 SDK
Use Sage as a library in your Rust projects:
```rust
use sage_sdk::{SageAgentSdk, RunOptions};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Load from config file
let sdk = SageAgentSdk::with_config_file("sage_config.json")?;
// Or create with default config
// let sdk = SageAgentSdk::new()?;
// Run a task
let options = RunOptions::new().with_max_steps(30);
let result = sdk
.run_with_options("Create a README file", options)
.await?;
println!("Execution completed: {:?}", result.outcome());
Ok(())
}
```
## 🏗️ Architecture
```
sage/
├── crates/
│ ├── sage-core/ # Core agent logic, LLM providers, session, tools
│ ├── sage-cli/ # Command-line interface
│ ├── sage-sdk/ # High-level SDK for embedding
│ └── sage-tools/ # Built-in tool implementations
├── docs/ # Documentation
├── examples/ # Usage examples
└── benchmarks/ # Performance benchmarks
```
## 🧪 Benchmarks
Run the startup benchmark:
```bash
./benchmarks/startup.sh
```
Example output from the benchmark script:
```
Code Agent Startup Benchmark
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Agent Avg (ms)
────────────────────────────
sage 45
claude 520
aider 780
Sage is 11.5x faster than Claude Code
```
Benchmark results depend on hardware, shell startup cost, installed comparison tools, and the selected iteration count. Re-run the script locally before relying on the numbers.
## 📚 Documentation
- [User Guide](docs/user-guide/) - Getting started, configuration, usage
- [Architecture](docs/architecture/) - System design, components
- [Tools Reference](docs/tools/) - All available tools
- [Development](docs/development/) - Contributing, building
## 🤝 Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
```bash
# Clone
git clone https://github.com/majiayu000/sage
cd sage
# Build
cargo build --workspace --release
# Test
cargo test --workspace --all-targets
# Run
./target/release/sage --help
```
Local developer state directories such as `.claude/` and `.omx/` are
intentionally ignored and should not be committed.
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
Sage is a Rust rewrite inspired by [Trae Agent](https://github.com/bytedance/trae-agent), which is also MIT licensed.
Third-party attribution and retained original MIT notices are listed in [NOTICE](NOTICE).
## 🙏 Acknowledgments
Inspired by:
- [Claude Code](https://claude.ai/code) - Anthropic's CLI tool design
- [Trae Agent](https://github.com/bytedance/trae-agent) - ByteDance's agent architecture
- [Aider](https://github.com/paul-gauthier/aider) - AI pair programming
---
<div align="center">
**[⭐ Star us on GitHub](https://github.com/majiayu000/sage)** if you find Sage useful!
Made with 🦀 by the Sage Team
</div>
连接信息
猜你喜欢
暂无推荐服务器