CLI-Agents-HQ

🤖 CLI Agents HQ

Secure, Multi-Agent Orchestration & Hybrid AI Dashboard

CLI Agents HQ is a professional management hub for your Gemini CLI agents. It transforms individual terminal interactions into a cohesive, team-based environment, allowing you to coordinate multiple AI specialists from a single, centralized command center.

🏛️ System Architecture

graph TD
    subgraph Local Environment
        T[Terminal] -->|CLI Commands| W(Local Worker)
        W -->|Reads/Writes| F[(Local Files/Project)]
    end
    
    subgraph Cloud Dashboard
        D{Next.js Admin Panel}
        D -->|WebSockets| S(Socket.io Server)
    end
    
    W <==>|Secure Bi-directional Sync| S
    S -->|Real-time UI| D
    
    classDef default fill:#0A0A0B,stroke:#F18E45,stroke-width:1px,color:#f1f1f1;
    classDef highlight fill:#F18E45,stroke:#fff,stroke-width:0px,color:#0a0a0b;
    class D highlight

🎯 What the app does

CLI Agents HQ bridges the gap between powerful AI execution and intuitive team management. It allows you to:

• Orchestrate specialized teams: "Hire" multiple agents and assign them expert roles (Architect, Security Auditor, Test Engineer, etc.) from a library of custom skills.
• Hybrid Local Execution: Securely connect your local terminal to an online dashboard. Your agents have full access to your local project files, while their progress and "Lessons Learned" are synced to the cloud.
• Session Persistence (New): Never lose a conversation. Full chat histories are now persisted on the server, allowing you to resume tasks even after a network disconnect.
• Multi-Worker Routing (New): Scale your team across multiple physical machines. The HQ now supports multiple concurrent local workers with sticky routing.
• Stall & Health Monitoring: Real-time heartbeat detection alerts you if an agent process hangs or takes too long to respond.
• Knowledge Search: Efficiently filter through your Knowledge Vault with a new server-side search engine.
• Collaborative Brainstorming: Use the Conference Room to start group chats where specialists build upon each other's ideas to solve complex problems.
• Unified Knowledge: Feed a global Project Brief or specific Knowledge Vault snippets to your entire team simultaneously.
• Persistent Evolution: Agents gain XP and level up from Junior to Senior as they "Reflect & Learn" from your conversations. Their insights are now extracted via structured JSON and synced using MD5 Content Hashing for maximum reliability.
• Windows Optimized: Deep integration for Windows terminal encoding (UTF-8) and multi-nested process handling.

🚀 How to Connect & Use

💾 Persistence Note (Updates)

When updating your HQ to a new version, always preserve your data.json and users.json files on the server. These files contain your agents' XP, levels, knowledge vault, and user accounts. If you are using the prepare-deploy.js script, ensure you download the live versions of these files to your local root before building, or exclude them from your server upload.

🔐 Default Login Credentials

Upon first deployment, use these credentials to access the dashboard:

• Username: Admin
• Password: admin123
• ⚠️ IMPORTANT: Change your password in the 👥 USERS menu immediately after logging in.

🛠️ Development & Testing

The project now includes a formal test suite to ensure architectural integrity.

npm install
npm test

1. Deploy the HQ (Server)

1. Upload the deploy-ready folder to your Plesk server.
2. In Plesk Node.js settings, set entry.js as the startup file.
3. Configuration: You can set Environment Variables in Plesk or create a .env file in the root:
   • CLI_AGENTS_SECRET_KEY: A strong secret for the local machine "handshake".
   • JWT_SECRET: A random string used to secure user login sessions.
   • PORT: (Optional) The port the server will run on (default: 5500).
4. Run NPM Install and Restart.

2. Connect the Engine (Local)

You can use the pre-bundled CLI Agents HQ Local folder, or set it up manually.

Using .env (New & Recommended)

1. Create a .env file in your local folder (see .env.example).
2. Add your SERVER_URL and CLI_AGENTS_SECRET_KEY.
3. Run node agent.js to connect instantly.

Option A: Automated (Legacy)

1. Copy the CLI Agents HQ Local folder to your computer.
2. Run npm install and node agent.js.
3. Follow the interactive prompts to enter your URL and Secret.

🆕 Changelogs

v1.7.0 (Smart Sync & Windows Power-Up)

• Automated Skill Sync: Bi-directional synchronization for the skills/ folder. The system now automatically detects which machine has the newest "Lessons Learned" and updates all connected instances (Server & Worker) instantly.
• Windows UTF-8 Fix: Automated chcp 65001 execution on startup. This eliminates Greek/Regional encoding errors (CP 737) and significantly speeds up terminal text streaming on Windows.
• Visual Reflection Feedback:
  • Global Logs: Successful reflections are now recorded in the System Logs with a brain icon (🧠) and knowledge snippets.
  • In-App Cues: The Reflect button provides immediate "LEARNING..." and "SUCCESS!" states.
• Data Protection: Updated prepare-deploy.js to include users.json in the deployment package.
• Stability: Hardened reflection logic to remove disruptive alert() boxes and replaced them with non-blocking UI notifications.

v1.6.0 (Unified Intelligence & Team Sync)

• Env Support: Integrated dotenv for seamless configuration via .env files.
• Conference Room 2.0: Complete UI redesign with a specialized sidebar and "Shared Memory" logic.
• Shared Memory: Agents in the Conference Room now "hear" each other by receiving the full room history.
• Global Brief Integration: The Project Brief is now automatically attached to every message (Individual & Team).
• Interactive Help: Added "💡 Help" buttons to Brief, Vault, and Conference Room for better onboarding.
• Gamified Evolution: Upgraded XP bars with smooth animations and added "Senior Status" visuals (Gold borders, sparkles, and dual-monitor icons) for Level 3+ agents.
• Permanent Learning: Fixed logic to ensure "Lessons Learned" are physically appended to your local skill markdown files.
• Security: Hardened .gitignore and added .env.example templates.
• Bug Fixes: Fixed socket relay logic for group messages and manual SEND button sync.

v1.5.2 (Complete Branding & Quick-Connect)

• Instant Setup: New 🔌 CONNECT button provides an auto-generated setup guide.
• Branding: Full transition to CLI Agents HQ with high-res logos and assets.
• Stability: Migrated all local machine interactions to high-stability Socket.io tunnels.

v1.5.1 (Secure Hybrid Mode)

• Security: Integrated JWT-based login system and role-based user management.
• Hybrid Logic: Dashboard stores state online while execution remains strictly local.
• UI UX: Added Full-Screen focus mode and real-time tab notifications.

Built for the next generation of secure, collaborative AI development.