YunTaiHua/illusion-agent
Illusion-Agent: Where fantasy meets functionality — an AI agent platform for terminal, browser, any model, any OS.
安装Install
dsh plugin --profile web add github:YunTaiHua/illusion-agent把 YunTaiHua/illusion-agent 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
IllusionAgent
Where fantasy meets functionality. The best of many worlds, refined into one intelligent agent.
中文版 | English
📖 Introduction
IllusionAgent is an open-source AI agent platform. It unifies a multi-provider LLM gateway, a bilingual (Chinese/English) CLI, a browser-based Web UI, and a flexible extension ecosystem into a single intelligent agent — at home on Windows, macOS, and Linux.
Whether you prefer the discipline of the terminal or the ease of the browser, IllusionAgent resonates with your workflow: 34 built-in tools, 7 specialized sub-agents, 2 compaction methods, MCP server support, hooks, plugins, and a cron scheduler for unattended automation — spanning Feishu, WeChat, and QQ.
Standing on the shoulders of giants — Claude Code prompts, OpenHarness architecture, OpenClaw scheduling, kimi-cli infrastructure, hermes-agent channels, cc-switch routing.
Core Features
- 🤖 Multi AI Provider Support - Anthropic, OpenAI, Copilot, Codex, and any compatible endpoint
- 🧠 Multi-Agent Collaboration - 7 built-in specialized Agents
- 🛠️ Rich Toolset - 34 built-in tools (30 base + 4 channel) + MCP dynamic tool extension
- 📦 Context Compaction - Microcompact (clear old tool results) + full compaction (LLM summary), auto-triggered as context fills
- 🌐 Web UI Interface - Browser-based chat interface with
illusion web, independently usable alongside the terminal - 🌍 Bilingual Interface - Chinese/English auto-switch via
ui_languagesetting - 📝 Comprehensive Markdown Rendering - Tables, code blocks, rich text
- 🔌 Flexible Extension System - Plugins, hooks, skills, MCP servers
- 🔐 Comprehensive Permission Control - Three modes + fine-grained rules
- 🎯 Reasoning Effort Control - low/medium/high/xhigh/max levels
- 🪟 Deep Windows Optimization - Auto-detect Git, PowerShell support
- 🖥️ Zero Terminal Flicker - Stable rendering based on Ink Static component
- 📦 Desktop Edition - Electron shell with bundled Python/Node.js, portable builds for Windows/macOS/Linux, zero environment setup
Interface Preview
Welcome screen & rich text rendering
🚀 Quick Start
Requirements
- Python >= 3.10
- Supports Windows, macOS, Linux
- Node.js 18+ (only for source install;
pip install illusion-agentdoes not require Node.js)
Installation
# Recommended: pip install from PyPI (no Node.js required)
pip install illusion-agent
# Alternative: from source (requires Node.js 18+)
git clone https://github.com/YunTaiHua/illusion-agent.git
cd illusion-agent
pip install .
Desktop Edition
Prefer a desktop app without installing Python or Node.js? Download the portable build for your platform — extract and run, zero environment setup:
| Platform | Download |
|---|---|
| Windows | IllusionAgent-<version>-win-x64.zip |
| macOS | IllusionAgent-<version>-arm64.dmg |
| Linux | IllusionAgent-<version>.AppImage |
👉 Download from GitHub Release
The desktop edition bundles Python 3.12 and Node.js 20 runtimes internally. See Desktop Edition docs for details.
Basic Usage
# First-time: configure authentication and working directory
illusion auth login
# Start interactive session (recommended)
illusion
# Launch Web UI in browser
illusion web
# Non-interactive print mode
illusion -p "Analyze the structure of this project"
# Set or update working directory
illusion set "E:\Projects\my-project"
Print Mode Notes
-p / --print runs a single non-interactive request and exits:
# Read-only analysis (safe, default permission mode)
illusion -p "Analyze the structure of this project"
# Allow file writes / command execution without interactive approval
illusion --permission-mode full_auto -p "Fix the failing tests"
# Resume after the process exits with code 2 (pending question/permission/plan)
illusion -c -p "Y"
# Specify model and effort for print mode
illusion -m env_1.model_2 -e high -p "Refactor this module"
Important details:
- The prompt value must be the last argument because typer parses
-pgreedily. - In default permission mode, mutating tools exit with code 2 and persist a pending approval; answer it with
illusion -c -p "Y","F", or"N". - Exit codes:
0success,1error,2waiting for cross-turn input.
Interface Notes
The terminal (illusion) and Web UI (illusion web) are two independent, first-class interfaces. They share the same backend runtime, settings, and session storage — use whichever fits your workflow.
📚 Detailed Documentation
| Topic | English | 中文 |
|---|---|---|
| Introduction | docs/en/introduction.md | docs/zh-CN/introduction.md |
| Getting Started | docs/en/getting-started.md | docs/zh-CN/getting-started.md |
| Commands | docs/en/commands.md | docs/zh-CN/commands.md |
| Goal (Auto-Continuation) | docs/en/goal.md | docs/zh-CN/goal.md |
| Settings & Credentials | docs/en/settings.md | docs/zh-CN/settings.md |
| Project Files & Memory | docs/en/project-files.md | docs/zh-CN/project-files.md |
| Extensions (MCP, Plugins, Skills, Hooks) | docs/en/extensions.md | docs/zh-CN/extensions.md |
| Architecture | docs/en/architecture.md | docs/zh-CN/architecture.md |
| Web UI Security | docs/en/security.md | docs/zh-CN/security.md |
| Token Metering & Compaction | docs/en/token-metering.md | docs/zh-CN/token-metering.md |
| Messaging Channels | docs/en/channels.md | docs/zh-CN/channels.md |
| Desktop Edition | docs/en/desktop.md | docs/zh-CN/desktop.md |
📄 License
This project is open-sourced under the MIT license.
🤝 Contributing
Welcome to submit Issues and Pull Requests!
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…