HyperChat

# HyperChat English Documentation # HyperChat > 🌟 **Local AI Agent Platform** - Pioneering the AI as Code concept, giving every 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 own a true project-level AI expert. ### 🎯 Core Features - 🏠 **Fully Localized**: Data stays local, ensuring privacy and security. - 🧠 **Agent Memory**: AI Agent understands and remembers your project context. - 📁 **Configuration as Code**: All AI capabilities are configured through files, supporting Git management. - 🔧 **Deep Tool Integration**: MCP protocol support allows direct manipulation of the local file system. - 📦 **One-Click Migration**: Complete `.hyperchat/` configuration directory migrates with the project. - 📂 **Multi@File Paths**: Smart 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 completely handcrafted project that is migrating to 2.0. **HyperChat 2.0** invites 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 Philosophy**: Project-level collaboration with unified resource management. - **🗂️ Multi-Workspace Tab Management**: Open multiple project workspaces simultaneously with one-click switching. - **👥 Team Collaboration Optimization**: Workspace-level Agent collections and MCP service pools. - **📊 Visual Management Interface**: Graphical configuration, real-time monitoring, and data statistics. - **💼 Applicable Scenarios**: Project development, team collaboration, workspace management, visual operations. ### 💻 CLI Frontend: Agent-Prioritized Quick Interaction **Design Philosophy**: Centralized Agent, rapid startup of individual agents. - **⚡ Quick Startup**: Directly select an Agent and load MCP tools as needed from the workspace. - **🎯 Focused Conversations**: Agent-specific memory, context, and chat history. - **🔧 Flexible Toolchain**: Built-in MCP tools in the Agent, with fallback to shared workspace resources. - **🚀 Applicable Scenarios**: Quick conversations, automation scripts, command-line workflows, CI/CD integration. ### 📋 Architecture Comparison | Feature | 🌐 Web Multi-Workspace Mode | 💻 CLI Agent-Prioritized Mode | |---------|-----------------------------|-------------------------------| | **Core Philosophy** | | Design Center | 🗂️ Workspace Collaboration Center | 🤖 Direct Interaction with Agent | | Resource Management | Unified MCP Pool per Workspace | On-Demand Agent Startup of MCP | | Usage Method | Concurrent Management of Multiple Tabs | Rapid Startup of Single Agent | | **Interface Experience** | | Interface Style | 🖥️ Modern Web Interface | 📟 Command Line + 🎨 TUI | | Interaction Mode | Mouse Click + Form Operations | Keyboard Input + Command Parameters | | Real-Time Updates | ✅ SSE Streaming Push | ✅ Terminal Streaming Output | | **Applicable Scenarios** | | Main Use | Project Development, Team Collaboration | Quick Conversations, 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 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 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 Collections, MCP Services, and Chat History for Each Tab # ✅ Visual Configuration and Real-Time Monitoring # ✅ Team Collaboration and Project Management ``` ### 💻 CLI Agent-Prioritized Mode Usage Example ```bash # 🚀 Agent-Prioritized Quick Start - Core Features hyperchat agent list # Discover Available Agents (Global + Workspace) hyperchat agent mybot "Hello" # 🎯 Directly Start Agent, Load MCP as Needed hyperchat agent mybot chat # 🎯 Agent-Specific Conversation 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 This code performs poorly" # Agent Management (In Current Workspace or Globally) 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 # Show Help # CLI Mode Advantages: # ⚡ Direct Agent Startup, No Interface Switching Needed # 🔧 On-Demand Loading of MCP Tools from Workspace # 💾 Agent-Specific Memory and Chat History # 🚀 Suitable for Script Integration and Automation ``` ### 🔄 Dual-Mode Collaborative Work ```bash # Scenario 1: Development in Web hyperchat serve # Start Web Interface to Manage Projects # 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, configuring shared Agents 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 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** - Command-line passed 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 Endpoints 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 Technical Implementation HyperChat 2.0 adopts a **dual-layer architecture design**, providing optimized experiences 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**: - 🗂️ **Concurrent Management of Multiple Workspaces**: `WorkspaceManager-enhanced` supports caching multiple workspace instances. - 🔌 **Workspace-Level MCP Service Pool**: Unified MCP client management. - 📊 **Real-Time Data Synchronization**: SSE streaming push, independent state management for multiple tabs. - 🔄 **Configuration Merging Mechanism**: Intelligent merging of global and workspace configurations. #### 💻 CLI Layer: Agent-Prioritized Architecture ```typescript // CLI Frontend: Agent-Specific MCP Access const agentInstance = workspace.getAgentInstance(agentName); const client = agentInstance.getMCPClient(clientName); // Fallback to shared MCP in workspace (if needed) ``` **Technical Features**: - ⚡ **Direct Agent Startup**: Skip workspace initialization, directly access Agent instances. - 🔧 **On-Demand Toolchain Loading**: Progressive loading from built-in Agent tools to shared workspace resources. - 💾 **Exclusive Context**: Independent memory, chat history, and configuration management for Agents. - 🚀 **Ultra-Fast 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 services + CLI Agent prioritized 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 # Parameterized workspacePath │ └── electron/ # Electron app packaging └── docs/ # Dual-layer architecture documentation ``` ### 💼 Dual-Layer 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/ # 🗂️ 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-Prioritized 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**: Workspace-centric, suitable for project-level management and team collaboration. - 💻 **CLI Mode**: Agent-centric, supporting personal tool usage across projects. - 🔄 **Intelligent Merging**: 5-layer priority management of global and workspace configurations. - 💾 **Data Isolation**: Complete separation of project-level and personal-level data, preventing 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 Auto-Switching # personal-coder will remember the characteristics and context of different projects. ``` ### Agent Configuration and Custom Commands ✨**New Feature** #### Basic Agent 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 # 🔌 Use 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"] ``` #### Directory Structure for Custom Agent Commands ✨**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 (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 fix plan. 3. Give the complete code after the fix. 4. Explain the principles of the fix and best practices. 5. Provide suggestions to prevent similar issues. ``` ```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, architectural principles, team standards. 5. **Improvement Suggestions**: Specific optimization plans and alternative implementations. Please provide specific modification suggestions and code examples. ``` #### Usage Example ```bash # Use custom command 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 bug in the following code: # @./src/login.ts User login redirection exception # Requirements: # 1. Carefully analyze the root cause of the problem. # 2. Provide a detailed fix plan. # 3. Give the complete code after the fix. # 4. Explain the principles of the fix and best practices. # 5. Provide suggestions to prevent similar issues. # Use code review command hyperchat agent project-assistant "/review @./src/components/UserProfile.tsx" # Use 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 coding assistant across projects, supporting multiple tech stacks." modelKey: "gpt-4o" isConfirmCallTool: true # ⚡ Agent-specific MCP tools + fallback to workspace allowMCPs: ["terminal", "browser", "calculator"] prompt: | You are my personal coding assistant, proficient 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. Please refer to the [LICENSE](LICENSE) file for details.