Content
# Tool List
## HyperChat
> 🌟 **Local AI Agent Platform** - Pioneering AI as Code, enabling each project to have its own dedicated AI brain
HyperChat is a revolutionary **local AI Agent platform** that allows for complete local AI capabilities through **configuration file-driven** approach, making AI abilities fully local, transferable, and version-controllable. Say goodbye to cloud dependencies and own your project-level AI expert.
### 🎯 Core Features
- 🏠 **Completely Localized**: Data stays local, ensuring privacy and security
- 🧠 **Agent Memory**: AI Agent understands and remembers your project context
- 📁 **Configuration as Code**: All AI capabilities configured through files, supporting Git management
- 🔧 **Deep Tool Integration**: MCP protocol support for direct operation on the local file system
- 📦 **One-Click Migration**: Complete `.hyperchat/` configuration directory for easy project migration
- 📂 **Multi-File Path Support**: Intelligent recognition of multiple file references, supporting complex file operations ✨**New Feature**
- 🎯 **Agent Custom Commands**: Markdown template-driven quick 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 manually written project, currently being migrated to 2.0.
**HyperChat 2.0** aims for everyone to **Vibe Coding**, welcoming the use of 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 Concept**: Project-level collaboration, unified resource management
- **🗂️ Multi-Workspace Tab Management**: Open multiple project workspaces simultaneously, with one-click switching
- **👥 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 operation
### 💻 CLI Frontend: Agent-First Rapid Interaction
**Design Concept**: Agent-centric, rapid launch of single intelligent agents
- **⚡ Quick Launch**: Directly select Agent, load MCP tools as needed from the workspace
- **🎯 Focus on Conversation**: Agent-exclusive memory, context, chat history
- **🔧 Flexible Toolchain**: Agent-built-in MCP tools, fallback to shared workspace resources
- **🚀 Applicable Scenarios**: Rapid conversation, automation scripts, command-line workflow, CI/CD integration
### 📋 Architecture Comparison
| Features | 🌐 Web Multi-Workspace Mode | 💻 CLI Agent-First Mode |
|---------|---------------------|----------------------|
| **Core Concept** |
| Design Center | 🗂️ Workspace Collaboration Center | 🤖 Agent Direct Interaction |
| Resource Management | Workspace unified MCP pool | Agent launches MCP on demand |
| Usage Method | Multi-tab concurrent management | Single Agent quick launch |
| **Interface Experience** |
| Interface Style | 🖥️ Modern Web Interface | 📟 Command Line + 🎨 TUI |
| Interaction Mode | Mouse click + form operation | Keyboard input + command parameters |
| Real-time Update | ✅ SSE streaming push | ✅ Terminal streaming output |
| **Applicable Scenarios** |
| Main Purpose | Project development, team collaboration | Rapid conversation, script integration |
| Usage Environment | Desktop browser, development IDE | Terminal, server, CI/CD |
| Workflow | Long-term project management | Temporary conversation handling |
## 🚀 Quick Experience
### ⌨️ Command Line Quick Launch
```bash
# Global installation
npm install -g @dadigua/hyperchat
# Or direct execution
npx -y @dadigua/hyperchat
```
**Quick Environment Variable Configuration**:
```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 directly
hyperchat "Hello, World!" # Use configured default model
```
### 🌐 Web Multi-Workspace Mode Usage Example
```bash
# Launch multi-workspace web interface
hyperchat serve # Visit: http://localhost:16100
# Web interface features:
# ✅ Multi-workspace tab management
# ✅ Independent Agent collection, MCP services, chat records for each tab
# ✅ Visual configuration and real-time monitoring
# ✅ Team collaboration and project management
```
### 💻 CLI Agent-First Mode Usage Example
```bash
# 🚀 Agent-first quick launch - Core features
hyperchat agent list # Discover available Agents (global + workspace)
hyperchat agent mybot "Hello" # 🎯 Directly launch Agent, load MCP as needed
hyperchat agent mybot chat # 🎯 Agent-exclusive conversation session
# Rapid AI chat (using default Agent)
hyperchat "Hello, how are you?" # Direct chat with 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 @./src/index.ts code quality"
hyperchat "Compare @./package.json and @./yarn.lock"
hyperchat "Please compare @./src/components/ and @./docs/ structure"
# 🎯 Agent custom commands - Quick input professional prompts ✨New Feature
hyperchat agent coder "/bug-fix @./src/login.ts login function abnormal"
hyperchat agent coder "/review @./src/api/user.js"
hyperchat agent coder "/optimize This code performance is poor"
# Agent management (in current workspace or global)
hyperchat agent create mybot # Create new Agent
hyperchat agent delete mybot # Delete Agent
# Workspace management
hyperchat workspace create # Create workspace in current directory
# Global options and workspace specification
hyperchat chat --workspace /path/to/project # Use specific workspace
hyperchat --verbose chat "Hello" # Detailed logs
hyperchat --help # Display help
# CLI mode advantages:
# ⚡ Agent direct launch, no interface switching
# 🔧 Load MCP tools on demand from workspace
# 💾 Agent-exclusive memory and chat history
# 🚀 Suitable for script integration and automation
```
### 🔄 Dual-Mode Collaboration
```bash
# Scenario 1: Development web
hyperchat serve # Launch web interface for project management
# Scenario 2: CI/CD automation using CLI
hyperchat agent test-runner "Run all tests and generate report"
# Scenario 3: Team collaboration using web
# Manage multiple project workspaces in the web interface, configure shared Agent and MCP services
```
### 🔧 Environment Variable Configuration
HyperChat 2.0 implements a powerful **5-layer priority environment variable system**, making configuration management more flexible:
**Priority order** (from low to high):
1. **Default values** - Built-in default configuration in code
2. **process.env** - System environment variables
3. **Global .env** - `~/Documents/HyperChat/.env`
4. **Workspace .env** - `.env` file in project directory
5. **CLI parameters** - Command-line parameters (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 endpoint
HYPERCHAT_OPENAI_BASE_URL=https://api.openai.com/v1
HYPERCHAT_CLAUDE_BASE_URL=https://api.anthropic.com
```
**Usage examples**:
```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 "Hello" # Directly use 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
echo "HyperChat_API_KEY=global-key" > ~/Documents/HyperChat/.env
echo "HyperChat_AI_Provider=gemini" >> ~/Documents/HyperChat/.env
```
## 🛠️ Technical Architecture
### 🎯 Dual-Layer Architecture Technology Implementation
HyperChat 2.0 adopts a **dual-layer architecture design**, providing the most optimized experience based on different usage scenarios:
#### 🌐 Web Layer: Workspace-Centric 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 multiple workspace instance caching
- 🔌 **Workspace-level MCP service pool**: Unified MCP client management
- 📊 **Real-time data synchronization**: SSE streaming push, multi-tab independent state management
- 🔄 **Configuration merging mechanism**: Intelligent merging of global configuration and workspace configuration
#### 💻 CLI Layer: Agent-First Architecture
```typescript
// CLI frontend: Agent-exclusive MCP access
const agentInstance = workspace.getAgentInstance(agentName);
const client = agentInstance.getMCPClient(clientName);
// Fallback to shared workspace MCP (if needed)
```
**Technical features**:
- ⚡ **Agent direct launch**: Omit workspace initialization, directly access Agent instance
- 🔧 **Toolchain loading on demand**: Progressive loading from Agent-built-in tools to shared workspace resources
- 💾 **Exclusive context**: Agent-independent memory, chat history, configuration management
- 🚀 **Rapid response**: No UI rendering overhead, suitable for scripts and automation
```
HyperChat Dual-Layer Architecture/
├── packages/
│ ├── shared/ # Shared code and type definitions
│ ├── core/ # Node.js core service + 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/ # Workspace unified configuration directory
│ ├── mcp.json # 🔌 Workspace-level MCP service pool
│ ├── ai_models.json # 🤖 Workspace AI model configuration
│ ├── .env # Workspace environment variables
│ └── agents/ # 🗂️ Workspace Agent collection
│ ├── 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-first 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
```
**Dual-layer configuration core advantages**:
- 🌐 **Web mode**: Workspace-centric, suitable for project-level management and team collaboration
- 💻 **CLI mode**: Agent-centric, supporting cross-project personal tool usage
- 🔄 **Intelligent merging**: 5-layer priority management of global configuration and workspace configuration
- 💾 **Data isolation**: Project-level and personal-level data completely separated, not interfering with each other
```
## 🌟 AI as Code Revolutionary Advantages
### 🔄 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 practice 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 Personal Agent Usage
cd /project-a && hyperchat agent personal-coder "Analyze this project"
cd /project-b && hyperchat agent personal-coder "Analyze this project"
# Agent Memory and Context Automatic Switching
# personal-coder will remember the characteristics and context of different projects
### Agent Configuration and Custom Commands
#### Basic Agent Configuration
```yaml
# .hyperchat/agents/project-assistant/agent.yaml
name: "Project Assistant"
description: "A full-stack assistant designed specifically for this project with React + Node.js"
modelKey: "claude-3-5-sonnet"
isConfirmCallTool: false
# Use workspace-level MCP service pool
allowMCPs: ["filesystem", "git", "npm", "database"]
prompt: |
You are the exclusive AI assistant for this project, familiar with:
- Project architecture: React + TypeScript + Node.js
- Business domain: E-commerce platform development
- Team specifications: ESLint + Prettier + Jest
Please provide professional advice based on the project context.
tags: ["project", "fullstack", "ecommerce"]
```
#### Agent Custom Command Directory Structure
```markdown
.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 # Document generation command
└── chatlogs/ # Chat logs
```
#### Command Template Example (pure Markdown)
```markdown
# commands/bug-fix.md
Please help me fix the bug in the following code:
$ARG
Requirements:
1. Carefully analyze the root cause of the problem
2. Provide a detailed repair plan
3. Provide the complete code after repair
4. Explain the repair principle and best practices
5. Provide suggestions for preventing similar problems
```
```markdown
# 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, permission control, data leakage risks
4. **Best practices**: Design patterns, architecture principles, team specifications
5. **Improvement suggestions**: Specific optimization plans and alternative implementations
Please provide specific modification suggestions and code examples.
```
#### Usage Example
```bash
# Use custom commands for bug fixing
hyperchat agent project-assistant "/bug-fix @./src/login.ts User login jump exception"
# Actual content sent to AI:
# Please help me fix the bug in the following code:
# @./src/login.ts User login jump exception
# Requirements:
# 1. Carefully analyze the root cause of the problem
# 2. Provide a detailed repair plan
# 3. Provide the complete code after repair
# 4. Explain the repair principle and best practices
# 5. Provide suggestions for preventing similar problems
# Use code review command
hyperchat agent project-assistant "/review @./src/components/UserProfile.tsx"
# In interactive chat
hyperchat agent project-assistant chat
> /bug-fix This function has a memory leak problem
> /optimize @./src/utils/dataProcessor.js
```
```yaml
# ~/Documents/HyperChat/.hyperchat/agents/personal-coder/agent.yaml
name: "Personal Coding Assistant"
description: "A general-purpose coding assistant across projects, supporting multiple technical stacks"
modelKey: "gpt-4o"
isConfirmCallTool: true
# Agent exclusive MCP tool + fallback to workspace
allowMCPs: ["terminal", "browser", "calculator"]
prompt: |
You are my personal coding assistant, good at:
- Multi-language development: Python, JavaScript, Go, Rust
- Architecture design and code review
- Rapid prototyping and problem-solving
Adjust your response style according to the context of different projects.
tags: ["personal", "general", "cross-project"]
```
### AI Model Recommendations
| Model Provider | Recommendation Level | Special Features |
|------------|----------|----------|
| Claude | | Best |
| Kimi k2 | | Very 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 development server
npm run dev
## Community交流
- [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 operation using this project (such as crawling behavior) is not related to the project developers.
## License
This project is open-sourced, please see the [LICENSE](LICENSE) file for details.
Connection Info
You Might Also Like
cc-switch
All-in-One Assistant for Claude Code, Codex & Gemini CLI across platforms.
awesome-mcp-servers
A collection of MCP servers.
git
A Model Context Protocol server for Git automation and interaction.
oh-my-opencode
Background agents · Curated agents like oracle, librarians, frontend...
TrendRadar
TrendRadar: Your hotspot assistant for real news in just 30 seconds.
Appwrite
Build like a team of hundreds