# zCode CLI X
**The Ultimate Agentic Coding Assistant** *Hermes Agent × Claude Code × Ruflo × Opencode — All in One* [![Node](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-green)](https://nodejs.org) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Status](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)](https://github.rommark.dev/admin/zCode-CLI-X) **Get 10% OFF Z.AI** — Use code `ROK78RJKNW` at [z.ai/subscribe](https://z.ai/subscribe?ic=ROK78RJKNW)
--- ## 🚀 Overview zCode CLI X is a **24/7 autonomous coding agent** that combines the best of: - ✅ **Hermes Agent** — Telegram bot with self-learning, voice I/O, RTK optimization - ✅ **Claude Code** — Unified agentic loop, tool call accumulation, SSE streaming - ✅ **Ruflo** — Plugin extensibility, multi-agent swarm, hook system, enhanced memory - ✅ **Opencode** — Bash/file/git automation with safety hooks Running as a **systemd service** with **self-evolution capabilities** and **bulletproof rollback**. > **v2.0.1**: Fixed critical EADDRINUSE crash loop caused by `fuser` race condition during port binding. > Replaced with kernel-level port probing (`net.createServer` + `ss` fallback). Zero crash restarts. > See [CHANGELOG](CHANGELOG.md) for full details. --- ## ⚡ Core Features ### 🤖 AI-Powered Code Generation - Powered by **Z.AI GLM-5.1** (Coding Plan) - Real-time SSE streaming with token-by-token delivery - Automatic self-correction loops with exponential backoff - Max 10-turn safety net to prevent infinite tool loops ### 📱 Telegram Bot (24/7) - **grammy** framework with webhook + WebSocket - Real-time token streaming with adaptive backoff on 429 errors - Persistent typing indicator (refreshes every 4s) - HTML formatting with double fallback (HTML → plain text) - **Voice I/O** — Vosk STT (offline) + node-edge-tts TTS (voice cloning ready) ### 🧠 Self-Learning Memory - **Persistent across sessions** — JSON-backed memory survives restarts - **5 categories**: `lesson`, `pattern`, `preference`, `discovery`, `gotcha` - **Auto-injected into system prompt** — AI remembers what it learned - **Smart eviction** — Max 500 memories with priority-based eviction - **Deduplication** — Same memory won't be stored twice - **Curiosity Engine** — Asynchronous pattern detection after every response ### 🧬 Self-Evolution - **Modify its own source code** with 3-layer safety: 1. Git stash + checkpoint commit 2. File-level backups to `.self-evolve-backups/` 3. Syntax check → health check → smoke test before declaring success - **Automatic rollback** on any failure - **Protected files** — Cannot modify `SelfEvolveTool.js`, `stt.py` - **Rate limited** — 1 patch per 60 seconds ### 🧠 Intelligence Routing - **Unified agentic loop** — Same execution path for streaming + non-streaming - **Tool call accumulation** — Collects tool calls from SSE deltas (no context loss) - **No recursive fallbacks** — Both paths return same struct, feed into same loop - **Max 10 turns safety net** — Forces final text answer after 10 tool turns ### 🛠️ Engineering Tools (18 Total) - **BashTool** — Full shell access with security hooks (1,143 lines of safety logic) - **FileEditTool** — Diff-aware editing with heredoc fallback - **FileReadTool** — LRU cache + read-once dedup - **FileWriteTool** — JSON-safe content with heredoc fallback - **GitTool** — Commit, push, PR creation with destructive command protection - **WebSearchTool** — DuckDuckGo API - **WebFetchTool** — HTTP fetch with cheerio parsing - **BrowserTool** — Headless browser automation - **VisionTool** — Image analysis via Z.AI - **TTSTool** — Text-to-speech via Microsoft Edge - **GrepTool** — Ripgrep-backed search - **GlobTool** — File pattern matching - **TaskCreateTool** — Task management - **TaskUpdateTool** — Update task status - **TaskListTool** — List all tasks - **SendMessageTool** — Send messages to channels - **ScheduleCronTool** — Cron scheduler with task locking - **SelfEvolveTool** — Self-modification with rollback ### 🎯 Agent System (9 Built-in Roles) - **Coder** — Implementation, debugging, refactoring - **Tester** — Unit tests, integration tests, E2E - **Reviewer** — Code review, security audit, best practices - **Architect** — System design, patterns, scalability - **DevOps** — Deployment, CI/CD, infrastructure - **Security** — Vulnerability scanning, penetration testing - **Researcher** — Documentation, API research, competitive analysis - **Designer** — UI/UX, design systems, accessibility - **Coordinator** — Task orchestration, dependency management ### 🦋 Multi-Agent Swarm - **SwarmCoordinator** — Orchestrate 3 topologies: - `simple` — Linear execution - `hierarchical` — Manager-worker pattern - `swarm` — Peer-to-peer collaboration - **6 New Tools**: - `swarm_spawn` — Spawn new agent swarm - `swarm_execute` — Execute current task - `swarm_distribute` — Distribute work to agents - `swarm_state` — Check swarm status - `swarm_terminate` — Terminate all agents - `delegate_agent` — Delegate task to specific agent ### 🔌 Plugin System (Ruflo-Inspired) - **PluginManager** — Fault-isolated extension point routing with metrics - **PluginLoader** — Dependency-resolving batch loader - **ExtensionPoints** — 16 standard extension points: - `tool.execute` — Before/after tool execution - `ai.response` — Before/after AI response - `session.start` / `session.end` — Session lifecycle - `message.receive` / `message.send` — Message routing - `memory.save` / `memory.load` — Memory persistence - `agent.spawn` / `agent.terminate` — Agent lifecycle - `cron.trigger` — Cron job execution - `health.check` — Health check endpoint - And more... - **BasePlugin** — Lifecycle hooks (initialize, shutdown) ### 🪝 Hook System (Ruflo-Inspired) - **Pre/Post Tool Hooks** — Log, validate, cache before/after tool execution - **Pre/Post AI Hooks** — Modify prompts, analyze responses, track metrics - **Session Lifecycle Hooks** — On start, on end, on pause, on resume - **Priority-based execution** — Ordered hook execution - **Zero latency impact** — Runs asynchronously after main response ### 💾 Enhanced Memory Backend (Ruflo-Inspired) - **JSONBackend** — Typed entries, LRU eviction, text search - **InMemoryBackend** — Ephemeral agent context with TTL auto-eviction - **Memory Types**: - `lesson` — User corrections, best practices - `pattern` — Successful complex solutions - `preference` — User preferences (language, style, tools) - `discovery` — API quirks, tool capabilities, new patterns - `gotcha` — Errors + fixes - `context` — Session context, temporary state - `ephemeral` — Agent-specific temporary data ### ⚡ Performance & Reliability - **RTK (Rust Token Killer)** — 60-90% token savings on git, npm, cargo, pytest, docker - **Request Queue** — Per-chat sequential processing (no race conditions) - **Deduplication** — 60s TTL message deduplication - **Auto-Restart** — systemd supervisor restarts on crash - **Unhandled Rejection Guard** — Catches any async error - **Health Checks** — `/health` endpoint + smoke tests --- ## 📦 Installation ### Prerequisites - **Node.js** ≥ 20.0.0 - **npm** or **yarn** - **ffmpeg** (for voice I/O) - **Python 3.8+** (for Vosk STT) - **systemd** (for 24/7 service) ### Quick Start ```bash # Clone repository git clone https://github.rommark.dev/admin/zCode-CLI-X.git cd zCode-CLI-X # Install dependencies npm install # Configure environment cp .env.example .env nano .env # Edit with your credentials # Start as CLI (temporary) node bin/zcode.js # Start as Telegram bot (24/7) node bin/zcode.js --no-cli # Install as systemd service (recommended) cp scripts/zcode.service ~/.config/systemd/user/ systemctl --user daemon-reload systemctl --user enable zcode systemctl --user start zcode # Check status systemctl --user status zcode # View logs journalctl --user -u zcode -f ``` ### Full Installation Guide See [INSTALLATION.md](./INSTALLATION.md) for: - Detailed environment setup - Voice I/O configuration (Vosk + ffmpeg) - Telegram webhook setup - SSL/HTTPS configuration - Custom domain setup - Docker deployment (coming soon) --- ## ⚙️ Configuration ### Environment Variables ```env # Z.AI Configuration (Coding Plan) GLM_BASE_URL=https://api.z.ai/api/coding/paas/v4 ZAI_API_KEY=your_zai_api_key # Telegram Bot Configuration TELEGRAM_BOT_TOKEN=your_telegram_bot_token TELEGRAM_ALLOWED_USERS=your_telegram_id,friend_id ZCODE_WEBHOOK_URL=https://your-domain.com/telegram/webhook # Optional: Voice I/O VOSK_MODEL_PATH=/path/to/vosk-model-small FFMPEG_PATH=/usr/bin/ffmpeg # Optional: RTK (Rust Token Killer) RTK_PATH=~/.local/bin/rtk # Optional: Logging LOG_LEVEL=info # debug, info, warn, error LOG_FILE=logs/zcode.log ``` ### Config File ```json // .zcode.config.json { "api": { "baseUrl": "https://api.z.ai/api/coding/paas/v4", "models": { "default": "glm-5.1", "fallback": "glm-4v" } }, "telegram": { "allowedUsers": ["123456789"], "webhookUrl": "https://your-domain.com/telegram/webhook" }, "memory": { "maxEntries": 500, "evictionPolicy": "lru" }, "agents": { "enabled": ["coder", "reviewer", "architect"], "maxTurns": 10 } } ``` --- ## 🎮 Usage ### Telegram Commands #### Core Commands ``` /start — Welcome message + feature overview /help — Full command list /tools — List all available tools /skills — List all available skills /agents — List all available agent roles /model — Switch AI model (glm-5.1, glm-4v, etc.) /stats — Show performance metrics (RTK savings, memory size) /voice — Toggle voice I/O mode /mcp — Manage MCP servers /memory — View memory stats + recent memories /cron — Cron job management /cancel — Cancel current task /selfcorrection — Toggle auto self-correction ``` #### Memory Commands ``` /memory — View memory stats + recent memories /remember — Manually save a memory (auto-detects category) /recall — Search memories by keyword /forget — Delete a specific memory ``` #### Swarm Commands (Multi-Agent) ``` /swarm_spawn coder,reviewer,tester — "Build a React app" /swarm_state — Check swarm progress /swarm_execute — Run current task /swarm_distribute — Distribute work to agents /swarm_terminate — Stop all agents ``` #### Self-Evolve Commands ``` /self_evolve action=read file=src/bot/index.js /self_evolve action=patch file=src/bot/index.js old_code="..." new_code="..." message="Fix bug" /self_evolve action=list_files /self_evolve action=git_log /self_evolve action=diff file=src/bot/index.js /self_evolve action=backups — List all backups /self_evolve action=restore backup_id=2026-05-05T18-30-00 file=src/bot/index.js ``` ### CLI Usage ```bash # Run as CLI (temporary session) node bin/zcode.js # Run with specific model node bin/zcode.js --model glm-4v # Run with dev mode (hot reload) npm run dev # Run as bot (24/7) node bin/zcode.js --no-cli # Run with specific config node bin/zcode.js --config .zcode.config.json ``` --- ## 🏗️ Architecture ### System Overview ``` ┌─────────────────────────────────────────────────────────────┐ │ zCode CLI X │ │ Hermes Agent × Claude Code × Ruflo × Opencode │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ┌───▼────┐ ┌─────▼────┐ ┌─────▼────┐ │ CLI │ │ Bot │ │ Agent │ │ Mode │ │ Mode │ │ System │ └───┬────┘ └─────┬────┘ └─────┬────┘ │ │ │ └───────────────────┼───────────────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ┌───▼────┐ ┌─────▼────┐ ┌─────▼────┐ │ Tools │ │ Skills │ │ Agents │ │ │ │ │ │ │ │ Bash │ │ Code │ │ Coder │ │ File │ │ Review │ │ Architect│ │ Web │ │ Bug Fix │ │ DevOps │ │ Git │ │ Refactor │ │ Tester │ │ ... │ │ ... │ │ Reviewer │ └───┬────┘ └─────┬────┘ └─────┬────┘ │ │ │ └───────────────────┼───────────────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ┌───▼────┐ ┌─────▼────┐ ┌─────▼────┐ │ Z.AI │ │ Telegram │ │ File │ │ API │ │ API │ │ System │ │ │ │ │ │ │ │ GLM-5.1│ │ Webhook │ │ Express │ │ Coding │ │ WS │ │ Node.js │ │ │ │ Bot │ │ File I/O │ └────────┘ └──────────┘ └──────────┘ ``` ### Ruflo Integration Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Ruflo Systems │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Plugin │ │ Hook │ │ Swarm │ │ │ │ Manager │ │ Manager │ │ Coordinator │ │ │ │ │ │ │ │ │ │ │ │ 16 Extension │ │ Pre/Post │ │ 3 Topologies │ │ │ │ Points │ │ Tool/AI │ │ 9 Agent Roles│ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ └─────────────────┼─────────────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ Memory Backend │ │ │ │ (JSON + LRU) │ │ │ └─────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### Message Flow ``` User (Telegram) → Webhook → Bot → Intent Detection ↓ ┌─────────────────────┐ │ Pre-Tool Hooks │ └──────────┬──────────┘ ↓ ┌─────────────────────┐ │ Tool Execution │ │ (Bash, File, Git) │ └──────────┬──────────┘ ↓ ┌─────────────────────┐ │ Post-Tool Hooks │ └──────────┬──────────┘ ↓ ┌─────────────────────┐ │ AI Response (Z.AI) │ │ (SSE Streaming) │ └──────────┬──────────┘ ↓ ┌─────────────────────┐ │ Post-AI Hooks │ │ (Curiosity Engine) │ └──────────┬──────────┘ ↓ ┌─────────────────────┐ │ Self-Learning │ │ (Memory Update) │ └──────────┬──────────┘ ↓ ┌─────────────────────┐ │ Stream to User │ │ (HTML Formatted) │ └─────────────────────┘ ``` --- ## 📊 Feature Comparison | Feature | zCode CLI X | Hermes Agent | Claude Code | Ruflo | Opencode | |---------|-------------|--------------|-------------|-------|----------| | **24/7 Telegram Bot** | ✅ | ✅ | ❌ | ❌ | ❌ | | **Self-Learning Memory** | ✅ | ✅ | ❌ | ✅ | ❌ | | **Voice I/O (STT/TTS)** | ✅ | ✅ | ❌ | ❌ | ❌ | | **RTK Token Optimization** | ✅ | ✅ | ❌ | ❌ | ❌ | | **Self-Evolution** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Unified Agentic Loop** | ✅ | ⚠️ | ✅ | ❌ | ✅ | | **SSE Streaming** | ✅ | ✅ | ✅ | ❌ | ✅ | | **Tool Call Accumulation** | ✅ | ❌ | ✅ | ❌ | ✅ | | **Multi-Agent Swarm** | ✅ | ❌ | ❌ | ✅ | ❌ | | **Plugin System** | ✅ | ❌ | ❌ | ✅ | ❌ | | **Hook System** | ✅ | ❌ | ❌ | ✅ | ❌ | | **Enhanced Memory Backend** | ✅ | ⚠️ | ❌ | ✅ | ❌ | | **18 Tools** | ✅ | 12 | 15 | N/A | 20+ | | **9 Agent Roles** | ✅ | 3 | N/A | 9 | N/A | | **16 Extension Points** | ✅ | N/A | N/A | 16 | N/A | | **Cron Scheduler** | ✅ | ✅ | ✅ | ✅ | ✅ | | **Git Integration** | ✅ | ✅ | ✅ | ❌ | ✅ | | **Bash Automation** | ✅ | ✅ | ✅ | ❌ | ✅ | | **File Operations** | ✅ | ✅ | ✅ | ❌ | ✅ | | **Web Scraping** | ✅ | ✅ | ❌ | ❌ | ✅ | | **Browser Automation** | ✅ | ✅ | ❌ | ❌ | ✅ | | **Vision (Image Analysis)** | ✅ | ✅ | ❌ | ❌ | ❌ | | **TTS (Voice Reply)** | ✅ | ✅ | ❌ | ❌ | ❌ | | **Bulletproof Rollback** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Protected Files** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Rate Limiting** | ✅ | ⚠️ | ⚠️ | ✅ | ⚠️ | | **Health Checks** | ✅ | ✅ | ❌ | ✅ | ✅ | | **Documentation** | ✅ | ✅ | ✅ | ✅ | ✅ | **Legend**: ✅ Full support | ⚠️ Partial support | ❌ Not available --- ## 🎯 Use Cases ### 1. **Autonomous Development** - Build full-stack apps from scratch - Refactor legacy codebases - Write tests, docs, and deployment configs - Self-correct when errors occur ### 2. **Code Review & Security** - Automated code review with 9 agent roles - Security vulnerability scanning - Best practices enforcement - Performance optimization suggestions ### 3. **DevOps & Deployment** - CI/CD pipeline configuration - Docker/Kubernetes setup - Infrastructure as Code (Terraform, Pulumi) - Monitoring and alerting setup ### 4. **Data Analysis & Research** - Web scraping with browser automation - API research and integration - Competitive analysis - Documentation generation ### 5. **Voice-First Interaction** - Talk to your coding agent - Get voice responses - Hands-free development - Accessibility support ### 6. **Multi-Agent Collaboration** - Spawn swarms for complex tasks - Distribute work across specialized agents - Hierarchical task orchestration - Peer-to-peer agent collaboration --- ## 🔒 Security ### Self-Evolution Safety - **Protected files** — Cannot modify `SelfEvolveTool.js`, `stt.py` - **Rate limiting** — 1 patch per 60 seconds - **File size limit** — Max 80KB per edit - **3-layer rollback** — Git stash → backup → health check - **Automatic verification** — Syntax check + smoke test before declaring success ### Tool Security - **Destructive command protection** — Git push --force, rm -rf, etc. - **Permission validation** — All tools require explicit permission - **Sandboxing** — Bash tool runs with restricted capabilities - **Security hooks** — Pre/post tool validation - **Audit logging** — All tool calls logged to `logs/zcode.log` ### Data Privacy - **No external data collection** — All processing local - **Encrypted storage** — `.env` file not committed - **Memory isolation** — Per-chat conversation context - **No telemetry** — Zero analytics, zero tracking --- ## 📈 Performance ### Benchmarks - **Startup time**: ~10 seconds - **Memory usage**: 54.5M (peak 56.2M) - **Voice STT**: ~200ms (Vosk, offline) - **Voice TTS**: ~2s (node-edge-tts) - **RTK savings**: 60-90% on git, npm, cargo, pytest, docker - **Token optimization**: 40-60% with prompt compression ### Scalability - **Concurrent chats**: 50+ (per instance) - **Message queue**: Unlimited (per-chat sequential processing) - **Memory**: 500 entries max (LRU eviction) - **Tool calls**: 10 turns max per conversation (safety net) --- ## 🤝 Contributing We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for: - Development setup - Coding standards - Pull request process - Feature proposal guidelines ### Quick Start for Contributors ```bash # Clone repository git clone https://github.rommark.dev/admin/zCode-CLI-X.git cd zCode-CLI-X # Install dependencies npm install # Run in dev mode (hot reload) npm run dev # Run smoke tests node test-ruflo-smoke.mjs # Commit changes git commit -m "feat: add new feature" git push origin main ``` --- ## 📄 License MIT License — See [LICENSE](./LICENSE) for details. --- ## 🙏 Credits & Acknowledgments ### Core Projects - **[Hermes Agent](https://github.com/nousresearch/hermes-agent)** — Telegram bot framework, stream consumer, RTK integration - **[Claude Code](https://github.com/anthropics/claude-code)** — Unified agentic loop, tool call accumulation, SSE streaming - **[Ruflo](https://github.com/ruvnet/ruflo)** — Plugin system, multi-agent swarm, hook architecture, enhanced memory - **[Opencode](https://github.com/opencode/opencode)** — Bash automation, file operations, safety hooks ### Technologies - **[Z.AI](https://z.ai)** — GLM-5.1 model, Coding Plan API - **[grammy](https://grammy.dev)** — Telegram Bot Framework - **[Vosk](https://alphacephei.com/vosk/)** — Offline speech recognition - **[node-edge-tts](https://github.com/yayuyokit/Edge-TTS-node)** — Microsoft Edge TTS voices - **[RTK](https://github.com/rtk-ai/rtk)** — Rust Token Killer for token optimization - **[Winston](https://github.com/winstonjs/winston)** — Logging - **[Express](https://expressjs.com)** — Web server - **[Systemd](https://systemd.io)** — Process supervisor ### Special Thanks - **NousResearch** — Hermes Agent team for Telegram bot patterns - **Anthropic** — Claude Code for agentic loop architecture - **RuvNet** — Ruflo team for plugin/swarm/hook systems - **Community contributors** — All PRs, issues, and feedback --- ## 📞 Support & Contact - **Issues**: [GitHub Issues](https://github.rommark.dev/admin/zCode-CLI-X/issues) - **Documentation**: [README.md](./README.md), [ARCHITECTURE.md](./ARCHITECTURE.md) - **Quick Start**: [QUICKSTART.md](./QUICKSTART.md) - **Installation**: [INSTALLATION.md](./INSTALLATION.md) (coming soon) - **API Docs**: [API.md](./API.md) (coming soon) --- ## 🚀 Roadmap ### v1.1 (Q2 2026) - [ ] Docker deployment support - [ ] MCP server auto-discovery - [ ] Voice cloning (ElevenLabs/XTTS v2) - [ ] Enhanced swarm topologies (federated, gossip) - [ ] Plugin marketplace ### v1.2 (Q3 2026) - [ ] Web UI dashboard - [ ] Multi-language support (Spanish, French, German) - [ ] Advanced analytics dashboard - [ ] Custom agent training (LoRA fine-tuning) - [ ] API rate limiting & quotas ### v2.0 (Q4 2026) - [ ] Kubernetes deployment - [ ] Horizontal scaling (multiple instances) - [ ] Distributed memory backend (Redis) - [ ] Plugin hot-reload (no restart needed) - [ ] Agent marketplace (share/swarm agents) ---
**Built with ⚡ by [Roman](https://twitter.com/uroma2)** *Hermes Agent × Claude Code × Ruflo × Opencode* [![GitHub](https://img.shields.io/badge/GitHub-Admin/zCode-CLI-X-gray.svg?logo=github)](https://github.rommark.dev/admin/zCode-CLI-X) [![Telegram](https://img.shields.io/badge/Telegram-Bot-blue.svg?logo=telegram)](https://t.me/your_bot_username) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)