Content
# HyperChat Chinese Documentation
# HyperChat
> 🌟 **Local AI Agent Platform** - The first to introduce the concept of AI as Code, giving each project its own dedicated AI brain.
HyperChat is a revolutionary **Local AI Agent Platform** that fully localizes, migrates, and version-controls AI capabilities through a **configuration-driven** approach. Say goodbye to cloud dependencies and have a true project-level AI expert that belongs to you.
### 🎯 Core Features
- 🏠 **Fully Localized**: Data stays local, privacy and security are controllable
- 🧠 **Agent Memory**: The AI Agent understands and remembers the context of your project
- 📁 **Configuration as Code**: All AI capabilities are configured through files, supporting Git management
- 🔧 **Deep Tool Integration**: MCP protocol support, allowing direct manipulation of the local file system
- 📦 **One-Click Migration**: Complete `.hyperchat/` configuration directory migrates with the project
- 📂 **Multiple @ File Paths**: Smart recognition of multiple file references, supporting complex file operations ✨**New Feature**
- 🎯 **Agent Custom Commands**: Markdown template-driven shortcut command system ✨**New Feature**
[](https://github.com/BigSweetPotatoStudio/HyperChat/actions/workflows/build.yml)
[](https://www.npmjs.com/package/@dadigua/hyperchat)
[](https://npm-stat.com/charts.html?package=@dadigua/hyperchat)
## 🎯 Project Vision
**[HyperChat 1.0](./archive/README.1.md)** is a fully handcrafted project that is migrating to 2.0.
In **HyperChat 2.0**, let's all **Vibe Coding** together, and feel free to use AI tools like Claude Code and GitHub Copilot for development.
## 🎯 Dual-Layer Architecture Design
> **Innovative Dual-Mode Architecture** - Optimizing user experience based on different usage scenarios
### 🌐 Web Frontend: Multi-Workspace Collaboration Center
**Design Philosophy**: Project-level collaboration, unified resource management
- **🗂️ Multi-Workspace Tab Management**: Open multiple project workspaces simultaneously, switch with one click
- **👥 Team Collaboration Optimization**: Workspace-level Agent collection, MCP service pool
- **📊 Visual Management Interface**: Graphical configuration, real-time monitoring, data statistics
- **💼 Applicable Scenarios**: Project development, team collaboration, workspace management, visual operations
### 💻 CLI Frontend: Agent Prioritizes Fast Interaction
**Design Philosophy**: Centralized Agent, Rapid Startup of Individual Agents
- **⚡ Quick Startup**: Directly select Agent and load MCP tools on demand from the workspace
- **🎯 Focused Conversations**: Agent-specific memory, context, and chat history
- **🔧 Flexible Toolchain**: Built-in MCP tools within the Agent, fallback to shared resources in the workspace
- **🚀 Applicable Scenarios**: Quick conversations, automation scripts, command line workflows, CI/CD integration
### 📋 Architecture Comparison
| Feature | 🌐 Web Multi-Workspace Mode | 💻 CLI Agent Priority Mode |
|---------|-----------------------------|---------------------------|
| **Core Concept** |
| Design Center | 🗂️ Workspace Collaboration Hub | 🤖 Direct Interaction with Agent |
| Resource Management | Unified MCP Pool for Workspaces | MCP Started on Demand by Agent |
| Usage Method | Concurrent Management with Multiple Tabs | Quick Start with Single Agent |
| **Interface Experience** |
| Interface Style | 🖥️ Modern Web Interface | 📟 Command Line + 🎨 TUI |
| Interaction Mode | Mouse Clicks + Form Operations | Keyboard Input + Command Parameters |
| Real-Time Updates | ✅ SSE Streaming Push | ✅ Terminal Streaming Output |
| **Applicable Scenarios** |
| Main Use Cases | Project Development, Team Collaboration | Quick Conversations, Script Integration |
| Usage Environment | Desktop Browsers, Development IDEs | Terminal, Server, CI/CD |
| Workflow | Long-Term Project Management | Temporary Conversation Handling |
## 🚀 Quick Experience
### ⌨️ Command Line Quick Start
```bash
# Global Installation
npm install -g @dadigua/hyperchat
# Or run directly
npx -y @dadigua/hyperchat
```
**Quickly configure environment variables**:
```bash
# Basic Configuration - Set Default AI Model
export HyperChat_API_KEY=your-api-key # API Key
export HyperChat_API_URL=your-api-url # API Endpoint URL
export HyperChat_AI_Provider=openai # AI Provider (openai/claude/gemini/kimi/qwen, etc.)
export HyperChat_AI_Model=gpt-4o # Default Model Name
# Then use it directly
hyperchat "Hello, World!" # Use the configured default model
```
### 🌐 Web Multi-Workspace Mode Usage Example
```bash
# Start Multi-Workspace Web Interface
hyperchat serve # Access: http://localhost:16100
# Web Interface Features:
# ✅ Multi-Workspace Tab Management
# ✅ Independent Agent Set, MCP Service, and Chat History for Each Tab
# ✅ Visual Configuration and Real-time Monitoring
# ✅ Team Collaboration and Project Management
```
### 💻 CLI Agent Priority Mode Usage Example
```bash
# 🚀 Agent Quick Start Priority - Core Features
hyperchat agent list # Discover available Agents (Global + Workspace)
hyperchat agent mybot "你好" # 🎯 Directly start Agent, load MCP on demand
hyperchat agent mybot chat # 🎯 Agent exclusive chat session
# Quick AI Chat (Using Default Agent)
hyperchat "Hello, how are you today?" # Chat directly with the default model
hyperchat chat "Write a Python script" # Chat command
hyperchat chat # Interactive chat mode
# 📁 Intelligent File Processing - Multi @ Symbol Support ✨ New Feature
hyperchat "Analyze the code quality of @./src/index.ts"
hyperchat "Compare @./package.json and @./yarn.lock"
hyperchat "Please compare the structure of @./src/components/ and @./docs/"
# 🎯 Agent Custom Commands - Quick Input of Professional Prompts ✨ New Feature
hyperchat agent coder "/bug-fix @./src/login.ts login function exception"
hyperchat agent coder "/review @./src/api/user.js"
hyperchat agent coder "/optimize the performance of this code is not good"
# Agent Management (in the current workspace or globally)
hyperchat agent create mybot # Create a new Agent
hyperchat agent delete mybot # Delete the Agent
# Workspace Management
hyperchat workspace create # Create a workspace in the current directory
# Global Options and Workspace Specification
hyperchat chat --workspace /path/to/project # Use a specific workspace
hyperchat --verbose chat "你好" # Detailed logs
hyperchat --help # Display help
# Advantages of CLI Mode:
# ⚡ Agent Direct Launch, No Interface Switching Required
# 🔧 Load MCP Tools on Demand from Workspace
# 💾 Agent Exclusive Memory and Chat History
# 🚀 Suitable for Script Integration and Automation
```
### 🔄 Dual-Mode Collaborative Work
```bash
# Scenario 1: Web during Development
hyperchat serve # Start the Web interface to manage the project
# Scenario 2: CI/CD Automation Using CLI
hyperchat agent test-runner "Run all tests and generate report"
# Scenario 3: Team Collaboration Using Web
# Managing Multiple Project Workspaces in the Web Interface, Configuring Shared Agents and MCP Services
```
### 🔧 Environment Variable Configuration
HyperChat 2.0 implements a powerful **5-level priority environment variable system**, making configuration management more flexible:
**Priority Order** (from low to high):
1. **Default Values** - Built-in default configurations in the code
2. **process.env** - System environment variables
3. **Global .env** - `~/Documents/HyperChat/.env`
4. **Workspace .env** - `.env` file in the project directory
5. **CLI Parameters** - Parameters passed via the command line (highest priority)
**Supported Core Environment Variables**:
```bash
# Quick Configuration - Default AI Model
HyperChat_API_KEY=your-api-key # Default API Key
HyperChat_API_URL=your-api-url # Default API Endpoint
HyperChat_AI_Provider=openai # Default AI Provider
HyperChat_AI_Model=gpt-4o # Default Model Name
# Service Configuration
HYPERCHAT_WEB_PASSWORD=your-web-password # Web interface access password
HYPERCHAT_PORT=16100 # Web service port
HYPERCHAT_HOST=localhost # Service binding address
# Interface Configuration
HYPERCHAT_LANGUAGE=zh # Interface language (zh/en)
HYPERCHAT_LOG_LEVEL=info # Log level
# Custom API Endpoints
HYPERCHAT_OPENAI_BASE_URL=https://api.openai.com/v1
HYPERCHAT_CLAUDE_BASE_URL=https://api.anthropic.com
```
**Usage Example**:
```bash
# Method 1: Quick Configuration of Default Model
export HyperChat_API_KEY=sk-1234567890
export HyperChat_AI_Provider=openai
export HyperChat_AI_Model=gpt-4o
hyperchat "你好" # Directly use the default configuration
# Method 2: Web Service Configuration
export HYPERCHAT_WEB_PASSWORD=mypassword
hyperchat serve
# Method 3: Project .env File
echo "HyperChat_API_KEY=your-key" > .env
echo "HyperChat_AI_Provider=claude" >> .env
hyperchat chat
# Method 4: CLI Parameters (Highest Priority)
hyperchat serve --password=clipass
# Method 5: Global Configuration File
```bash
echo "HyperChat_API_KEY=global-key" > ~/Documents/HyperChat/.env
echo "HyperChat_AI_Provider=gemini" >> ~/Documents/HyperChat/.env
```
## 🛠️ Technical Architecture
### 🎯 Dual-Layer Architecture Technical Implementation
HyperChat 2.0 adopts a **dual-layer architecture design** to provide an optimized experience based on different usage scenarios:
#### 🌐 Web Layer: Workspace Center Architecture
```typescript
// Web Frontend: Unified MCP Management for Workspaces
const workspace = workspaceManager.get(workspacePath);
const mcpManager = workspace.getMcpManager();
const client = mcpManager.getClient(clientName);
```
**Technical Features**:
- 🗂️ **Multi-Workspace Concurrent Management**: `WorkspaceManager-enhanced` supports caching of multiple workspace instances
- 🔌 **Workspace-Level MCP Service Pool**: Unified MCP client management
- 📊 **Real-Time Data Synchronization**: SSE (Server-Sent Events) streaming push, independent state management for multiple tabs
- 🔄 **Configuration Merging Mechanism**: Intelligent merging of global configuration + workspace configuration
#### 💻 CLI Layer: Agent First Architecture
```typescript
// CLI Frontend: Agent dedicated MCP access
const agentInstance = workspace.getAgentInstance(agentName);
const client = agentInstance.getMCPClient(clientName);
// Fallback to workspace shared MCP (if needed)
```
**Technical Features**:
- ⚡ **Direct Agent Launch**: Skips workspace initialization, directly accesses the Agent instance
- 🔧 **On-Demand Toolchain Loading**: Progressive loading from built-in Agent tools to workspace shared resources
- 💾 **Dedicated Context**: Independent memory, chat history, and configuration management for the Agent
- 🚀 **Ultra-Fast Response**: No UI rendering overhead, suitable for scripting and automation
```
HyperChat Dual-Layer Architecture/
├── packages/
│ ├── shared/ # Shared code and type definitions
│ ├── core/ # Node.js core services + CLI Agent first layer
│ │ ├── src/cli/ # 💻 CLI Agent direct interaction layer
│ │ ├── src/workspace/ # Dual-layer workspace management system
│ │ │ ├── workspaceManager-enhanced.mts # 🌐 Multi-workspace concurrent management
│ │ ├── src/mcp/ # MCP protocol implementation
│ │ └── src/commands/ # Web API command system
│ ├── web/ # 🌐 React Web multi-workspace layer
│ │ ├── src/pages/workspace/ # Multi-workspace management components
│ │ │ ├── WorkspaceManage.tsx # Multi-tab manager
│ │ │ └── workspace.tsx # Single workspace instance component
│ │ └── src/hooks/useChatStream.ts # workspacePath parameterization
│ └── electron/ # Electron application packaging
└── docs/ # Dual-layer architecture documentation
```
### 💼 Dual-layer Architecture Configuration Management
```
🌐 Web Multi-workspace Mode Configuration:
project-directory/
├── .hyperchat/ # Unified configuration directory for workspaces
│ ├── mcp.json # 🔌 Workspace-level MCP service pool
│ ├── ai_models.json # 🤖 Workspace AI model configuration
│ ├── .env # Workspace environment variables
│ └── agents/ # 🗂️ Collection of workspace Agents
│ ├── project-assistant/ # Project-specific Agent
│ │ ├── agent.yaml # Agent configuration
│ │ ├── memory.md # Project context memory
│ │ └── chatlogs/ # Team conversation history
│ └── code-reviewer/ # Code review Agent
├── .git/ # Version control
└── package.json # Project configuration
💻 CLI Agent Priority Mode Access:
Global Configuration/
~/Documents/HyperChat/
.hyperchat/
├── mcp.json # 🌍 Global MCP service pool
├── .env # Global environment variables
└── agents/ # 🚀 Global Agent library
├── personal-assistant/ # Personal assistant Agent
│ ├── agent.yaml # Agent configuration
│ ├── memory.md # Personal context memory
│ └── chatlogs/ # Personal conversation history
└── code-expert/ # Professional code Agent
```
**Core Advantages of Dual-layer Configuration**:
- 🌐 **Web Mode**: Centralized workspace, suitable for project-level management and team collaboration
- 💻 **CLI Mode**: Centralized Agents, supporting personal tool usage across projects
- 🔄 **Intelligent Merging**: 5-layer priority management of global configuration + workspace configuration
- 💾 **Data Isolation**: Complete separation of project-level and personal-level data, with no interference
## 🌟 Revolutionary Advantages of AI as Code
### 🔄 Intelligent Management under Dual-Layer Architecture
#### 🌐 Web Mode: Team Collaboration Version Control
```bash
# 📁 Project-Level AI Configuration Version Management
git add .hyperchat/agents/project-assistant/
git commit -m "Add project-specific AI assistant"
git push origin feature/project-ai
# 👥 Team AI Best Practices Sharing
git clone https://github.com/team/ai-workspace-templates.git
cp -r ai-workspace-templates/react-fullstack/.hyperchat ./
# 🔄 Project AI Configuration Rollback
git checkout HEAD~1 -- .hyperchat/
```
#### 💻 CLI Mode: Personal Tool Management
```bash
# 🚀 Quick Deployment of Personal Agent
hyperchat agent create personal-coder --template ~/ai-templates/
# 🌍 Cross-Project Use of Personal Agent
cd /project-a && hyperchat agent personal-coder "Analyze this project"
cd /project-b && hyperchat agent personal-coder "Analyze this project"
# 💾 Agent Memory and Context Switching
# personal-coder will remember the characteristics and context of different projects
```
### Agent Configuration and Custom Commands ✨**New Feature**
#### Agent Basic Configuration
```yaml
# .hyperchat/agents/project-assistant/agent.yaml
name: "Project Assistant"
description: "A full-stack assistant designed specifically for this project using React + Node.js"
modelKey: "claude-3-5-sonnet"
isConfirmCallTool: false
# 🔌 Using Workspace-Level MCP Service Pool
allowMCPs: ["filesystem", "git", "npm", "database"]
prompt: |
You are the dedicated AI assistant for this project, familiar with:
- Project Architecture: React + TypeScript + Node.js
- Business Domain: E-commerce Platform Development
- Team Standards: ESLint + Prettier + Jest
Please provide professional advice based on the project context.
tags: ["project", "fullstack", "ecommerce"]
#### Agent Custom Command Directory Structure ✨**New Feature**
```
.hyperchat/agents/project-assistant/
├── agent.yaml # Agent Configuration
├── memory.md # Agent Memory
├── commands/ # 🎯 Custom Command Directory
│ ├── bug-fix.md # Bug Fix Command
│ ├── review.md # Code Review Command
│ ├── explain.md # Code Explanation Command
│ ├── test.md # Test Case Command
│ ├── optimize.md # Code Optimization Command
│ └── document.md # Documentation Generation Command
└── chatlogs/ # Chat Logs
```
#### Command Template Example (Pure Markdown)
```markdown
# commands/bug-fix.md
Please help me fix the bugs in the following code:
$ARG
Requirements:
1. Carefully analyze the root cause of the problem
2. Provide a detailed fix plan
3. Present the complete code after the fix
4. Explain the principles of the fix and best practices
5. Offer suggestions to prevent similar issues
# commands/review.md
Please conduct a comprehensive code review of the following code:
$ARG
Review points:
1. **Code Quality**: readability, maintainability, naming conventions
2. **Performance Issues**: algorithm efficiency, memory usage, potential bottlenecks
3. **Security Risks**: input validation, access control, data leakage risks
4. **Best Practices**: design patterns, architectural principles, team standards
5. **Improvement Suggestions**: specific optimization proposals and alternative implementations
Please provide specific modification suggestions and code examples.
#### Usage Example
```bash
# Using Custom Commands for Bug Fixing
hyperchat agent project-assistant "/bug-fix @./src/login.ts User login redirection exception"
# Actual content sent to AI:
# Please help me fix the bugs in the following code:
# @./src/login.ts User Login Redirection Exception
# Requirements:
# 1. Carefully Analyze the Root Cause of the Problem
# 2. Provide Detailed Fix Solutions
# 3. Provide the complete code after the fix
# 4. Explanation of the Principles and Best Practices for Fixes
# 5. Provide Recommendations to Prevent Similar Issues
# Using Code Review Command
hyperchat agent project-assistant "/review @./src/components/UserProfile.tsx"
# Using in Interactive Chat
hyperchat agent project-assistant chat
> /bug-fix This function has a memory leak issue
> /optimize @./src/utils/dataProcessor.js
```
```yaml
# ~/Documents/HyperChat/.hyperchat/agents/personal-coder/agent.yaml
name: "Personal Coding Assistant"
description: "A general programming assistant across projects, supporting multiple tech stacks"
modelKey: "gpt-4o"
isConfirmCallTool: true
# ⚡ Agent Exclusive MCP Tools + Rollback to Workspace
allowMCPs: ["terminal", "browser", "calculator"]
prompt: |
You are my personal programming assistant, skilled in:
- Multi-language development: Python, JavaScript, Go, Rust
- Architecture design and code review
- Rapid prototyping and problem-solving
Adjust your response style based on the context of different projects.
tags: ["personal", "general", "cross-project"]
```
### 🤖 AI Model Recommendations
| Model Provider | Recommendation Level | Featured Functions |
|----------------|---------------------|--------------------|
| Claude | ⭐⭐⭐⭐⭐⭐ | The strongest |
| Kimi k2 | ⭐⭐⭐⭐⭐ | Quite good |
## 🔧 Development Guide
### 💻 Local Development
```bash
# Clone the Project
git clone https://github.com/BigSweetPotatoStudio/HyperChat.git
cd HyperChat
# Install Dependencies
npm install
cd packages/electron && npm install
cd packages/web && npm install
cd ../..
# Start the Development Server
npm run dev
## 🤝 Community Communication
- [Telegram](https://t.me/dadigua001)
- [QQ Group](https://qm.qq.com/cgi-bin/qm/qr?k=KrNWdu5sp7H3ves3ZPSd7ppKjQiPrAvZ&jump_from=webapi&authKey=xnW+Lcgk5KLh5NPh3lU0ddz9CFDbXgvjEy35wsYipUrCsqXFcqlvM5Yorh6jkGim)
## 📄 Disclaimer
This project is for learning and communication purposes only. Any actions taken using this project (such as web scraping, etc.) are not related to the project developers.
## 📜 License
This project is licensed under an open-source license. For details, please see the [LICENSE](LICENSE) file.
