# Sage
**Repository Path**: NovemberRain/Sage
## Basic Information
- **Project Name**: Sage
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-08-11
- **Last Updated**: 2026-04-28
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# ๐ **Experience Sage's Power**
[](README.md)
[](README_CN.md)
[](LICENSE)
[](https://python.org)
[](https://github.com/ZHangZHengEric/Sage)
[](https://deepwiki.com/ZHangZHengEric/Sage)
[](https://join.slack.com/t/sage-b021145/shared_invite/zt-3t8nabs6c-qCEDzNUYtMblPshQTKSWOA)
# ๐ง **Sage Agent Platform**
### ๐ฏ **From Complex Work to Reliable Delivery**
> ๐ **A production-ready agent platform for task execution, automation, browser workflows, IM delivery, and enterprise deployment.**
---
## ๐ธ **Product Screenshots**
Visual Workbench
|
Real-time Collaboration
|
Multi-format Support
|
> ๐ **Detailed Documentation**: [https://wiki.sage.zavixai.com/](https://wiki.sage.zavixai.com/)
---
## โจ **Key Features**
- ๐ค **Planning to Delivery**: Built-in planning, execution, self-check, memory recall, and tool suggestion agents for complex task completion.
- ๐ **Multi-Entry Product Surface**: Use Sage from desktop, web, CLI, and Chrome extension depending on the workflow.
- ๐ **Automation & Recurring Tasks**: Run scheduled jobs, questionnaire-driven collection flows, and long-running operational tasks with progress visibility.
- ๐ฌ **Omnichannel IM Integration**: Connect WeChat Personal (iLink), WeCom, Feishu, and DingTalk with message and file delivery support.
- ๐งฐ **Unified Tooling System**: Combine built-in tools, Skills, MCP servers, browser automation, search, and image generation in one execution stack.
- ๐ก๏ธ **Sandboxed Execution**: Local, passthrough, and remote sandbox options for safer agent runtime isolation.
- ๐ ๏ธ **Visual Workbench**: Inspect files, tool outputs, code, charts, Mermaid, Draw.io, audio, video, and remote previews in one workspace.
- ๐ข **Enterprise-Ready Foundation**: OAuth2, configurable auth and CORS, shared service architecture, CI coverage, and deployable multi-platform packaging.
---
## ๐ **Quick Start**
**Prerequisites (web from source):** Python 3.10+, Node.js 18+.
### Web (clone and run)
```bash
git clone https://github.com/ZHangZHengEric/Sage.git
cd Sage
export SAGE_DEFAULT_LLM_API_KEY="your-api-key"
export SAGE_DEFAULT_LLM_API_BASE_URL="https://api.deepseek.com/v1"
export SAGE_DEFAULT_LLM_MODEL_NAME="deepseek-chat"
./scripts/dev-up.sh
```
Open [http://localhost:5173](http://localhost:5173). The first run may ask for **Minimal** (SQLite) vs **Full** stacks โ Minimal is the quickest. Optional: `PYTHON_BIN=...` or `USE_UV=1 ./scripts/dev-up.sh` if you use a custom Python or [uv](https://github.com/astral-sh/uv).
**Detailed documentation:** [Web Application](docs/en/applications/WEB.md) โ manual backend + Vite, Docker Compose, and port notes.
### Desktop (installers)
Download the latest `.dmg` (macOS), `.exe` NSIS installer (Windows), or `.deb` (Linux) from [GitHub Releases](https://github.com/ZHangZHengEric/Sage/releases), then install as below.
**macOS**
1. Open the `.dmg` for your CPU (Intel or Apple Silicon), drag **Sage.app** into **Applications**.
2. The build is **not** currently Apple-notarized. If macOS says the developer cannot be verified or the app cannot be checked for malware: in **Finder โ Applications**, **rightโclick** `Sage.app` โ **Open**, then confirm **Open** in the dialog (this adds a one-time exception for Gatekeeper).
3. If it is still blocked: **System Settings โ Privacy & Security**, scroll to the message about Sage, click **Open Anyway**, then try opening the app again.
4. If macOS reports the app is **damaged** or will not open, clear the quarantine flag and retry:
```bash
xattr -dr com.apple.quarantine /Applications/Sage.app
```
**Windows**
1. Run the `.exe` installer and complete the wizard.
2. If **Windows SmartScreen** warns about an unknown publisher, click **More info** โ **Run anyway** (wording may vary by Windows version).
**Linux (Debian / Ubuntu)**
1. Download the `.deb` for your architecture from Releases.
2. Install from a terminal (adjust the filename):
```bash
sudo apt install ./Sage--.deb
```
You can also double-click the `.deb` in many desktop environments.
**Detailed documentation:** [Desktop Application](docs/en/applications/DESKTOP.md) โ build from source, env, and platform notes.
### CLI
```bash
pip install -e .
export SAGE_DEFAULT_LLM_API_KEY="your-api-key"
export SAGE_DEFAULT_LLM_API_BASE_URL="https://api.deepseek.com/v1"
export SAGE_DEFAULT_LLM_MODEL_NAME="deepseek-chat"
export SAGE_DB_TYPE="file"
sage doctor
sage run "Say hello briefly."
# or: sage chat
```
**Detailed documentation:** [CLI Guide](docs/en/applications/CLI.md)
### TUI
After `pip install -e .` and the same `SAGE_DEFAULT_*` + `SAGE_DB_TYPE=file` as above, use `sage-terminal` (or run from `app/terminal/` with `cargo` โ see the guide).
**Detailed documentation:** [TUI Guide](docs/en/applications/TUI.md)
### Chrome extension
Load the unpacked extension from `app/chrome-extension/` in `chrome://extensions/` (Developer mode). Point the extension at your local Sage backend if the port differs from defaults.
**Detailed documentation:** [Chrome extension](docs/en/applications/CHROME_EXTENSION.md)
---
## ๐๏ธ **System Architecture**
```mermaid
graph TD
User[User] --> Desktop[๐ป Desktop App]
User --> Web[๐ Web App]
User --> CLI[โจ๏ธ CLI]
User --> Ext[๐งฉ Chrome Extension]
User --> IM[๐ฌ IM Channels]
Desktop --> AppLayer[๐งญ App Service Layer]
Web --> AppLayer
CLI --> AppLayer
Ext --> AppLayer
IM --> AppLayer
subgraph App[Product Layer]
AppLayer --> Chat[๐ฌ Chat & Sessions]
AppLayer --> AgentsUI[๐ค Agent Management]
AppLayer --> Tasks[โฐ Tasks & Automations]
AppLayer --> Browser[๐ Browser Bridge]
AppLayer --> Workbench[๐ ๏ธ Visual Workbench]
end
subgraph Core[SAgents Core]
AppLayer --> Runtime[๐ง Session Runtime]
Runtime --> Flow[๐ AgentFlow]
Flow --> Agents["๐ค Agents
Plan / Simple / Fibre / Self-Check"]
Agents --> Memory[๐ง Memory Recall]
Agents --> Skills[๐งฉ Skills]
Agents --> ToolMgr[๐ ๏ธ Tool Manager]
end
subgraph Tools[Execution & Integration]
ToolMgr --> MCP[๐ MCP Servers]
ToolMgr --> BrowserTools[๐ Browser Automation]
ToolMgr --> Search[๐ Unified Search]
ToolMgr --> ImageGen[๐จ Image Generation]
ToolMgr --> Questionnaire[๐ Questionnaire]
ToolMgr --> IMTools[๐จ IM Delivery]
end
subgraph RuntimeEnv[Runtime & Infrastructure]
Agents --> Sandbox[๐ฆ Sandbox Runtime]
Sandbox --> Local[Local]
Sandbox --> Pass[Passthrough]
Sandbox --> Remote[Remote]
AppLayer <--> Common[๐งฑ Shared Common Services]
Common <--> DB[(SQL Database)]
Memory <--> ES[(Elasticsearch)]
Workbench <--> FS[(RustFS / Local Files)]
Runtime -.-> Obs["๐๏ธ Observability
OpenTelemetry"]
end
```
---
## ๐
**What's New in v1.1.0**
### ๐ค **SAgents Kernel Updates**
- **Execution Chain Enhancements**: Added `PlanAgent`, `SelfCheckAgent`, `MemoryRecallAgent`, and `ToolSuggestionAgent`
- **Context Efficiency**: Improved user input optimization and conversation history compression for long-running tasks
- **Session & Messaging**: Added edit-and-rerun support, richer progress feedback, and better session inspection workflows
- **Tooling Expansion**: Added questionnaire collection workflows and improved tool-call rendering, truncation, and observability
### ๐ป **Product Layer Updates**
- **New Entry Points**: Added Sage CLI, Chrome extension, and browser automation tooling
- **Workbench Upgrades**: Expanded support for audio, video, Mermaid, Draw.io, remote file preview, and richer tool cards
- **Chat Experience**: Improved progress messages, delivery flow display, reasoning content presentation, and workspace interactions
- **IM Integrations**: Expanded WeChat Personal (iLink), WeCom, Feishu, and DingTalk support with stronger file messaging flows
### ๐ก๏ธ **Platform & Infrastructure**
- **Enterprise Readiness**: Added OAuth2, email verification, and stronger auth/CORS/security controls
- **Sandbox & Runtime**: Refactored local/passthrough/remote sandbox support and improved Node runtime/sidecar packaging
- **Shared Architecture**: Extracted reusable `common/` services, models, and schemas across desktop and server
- **Documentation & CI**: Rebuilt the docs structure, added CLI guides, and expanded CI/test coverage
**[View Full Release Notes](release_notes/v1.1.0.md)**
---
## ๐ **Documentation**
- ๐ **Full Documentation**: [https://wiki.sage.zavixai.com/](https://wiki.sage.zavixai.com/)
- ๐ **Release Notes**: [release_notes/](release_notes/)
- ๐๏ธ **Architecture**: See `sagents/`, `common/`, and `app/` for the core runtime and product layers
- ๐ง **Configuration**: Environment variables and config files in `app/desktop/`
---
## ๐ ๏ธ **Development**
### Project Structure
```
Sage/
โโโ sagents/ # SAgents core runtime, flow, context, tools, sandbox
โโโ common/ # Shared models, schemas, services, core clients
โโโ app/
โ โโโ desktop/ # Desktop app (Python backend + Vue UI + Tauri shell)
โ โโโ server/ # Server app and web frontend
โ โโโ cli/ # Sage CLI entrypoint and services
โ โโโ chrome-extension/ # Browser extension and sidepanel
โโโ mcp_servers/ # IM, search, scheduler, image generation and more
โโโ docs/ # English and Chinese documentation
โโโ release_notes/ # Version release notes
```
### Contributing
We welcome contributions! Please see our [GitHub Issues](https://github.com/ZHangZHengEric/Sage/issues) for tasks and discussions.
---
## ๐ **Sponsors**
We are grateful to our sponsors for their support in making Sage better:
### ๐ฌ Connect with us
[](https://join.slack.com/t/sage-b021145/shared_invite/zt-3t8nabs6c-qCEDzNUYtMblPshQTKSWOA)
### ๐ฑ WeChat Group
*Scan to join our WeChat community ๐ฆ*
Built with โค๏ธ by the Sage Team ๐ฆ
