zCode CLI X

The Ultimate Agentic Coding Assistant
Hermes Agent × Claude Code × Ruflo × Opencode — All in One

Get 10% OFF Z.AI — Use code ROK78RJKNW at z.ai/subscribe

---

🚀 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.2: Performance overhaul — 3x faster task execution. Hermes guardrail, OpenCode tool guidance, parallel execution. Fixed EADDRINUSE crash loop, Telegram formatting, and ghost chasing (47 turns → 15 turns). Studied Hermes, OpenCode, Ruflo. See CHANGELOG 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

# 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 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

# 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

// .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 <text> — Manually save a memory (auto-detects category)
/recall <query> — Search memories by keyword
/forget <id> — 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

# 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)   │
                          └─────────────────────┘

PortManager — Smart Port Lifecycle

Handles HTTP server port binding with intelligent recovery, replacing the old probe→kill→exit pattern that caused crash-loops under systemd.

PortManager (EventEmitter)
├── States: idle → probing → claiming → owned → releasing → failed
├── Holder Detection (3 methods):
│   ├── pidfile read (fast path)
│   ├── ss -tlnp (system socket lookup)
│   └── lsof -ti (fallback)
├── Recovery:
│   ├── Age-based kill strategy (young siblings waited, not killed)
│   ├── Exponential backoff retry (5 attempts, 500ms → 5000ms)
│   └── State events: stateChange, claimed, retry, failed
└── API:
    ├── claim(server) — acquire port with retry loop
    ├── release() — cleanup on shutdown
    ├── probe() — check if port is free
    └── getStatus() — diagnostics for health checks

File: src/bot/port-manager.js | Exposed via: bot.portManager

---

📊 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 for:

• Development setup
• Coding standards
• Pull request process
• Feature proposal guidelines

Quick Start for Contributors

# 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 for details.

---

🙏 Credits & Acknowledgments

Core Projects

• Hermes Agent — Telegram bot framework, stream consumer, RTK integration
• Claude Code — Unified agentic loop, tool call accumulation, SSE streaming
• Ruflo — Plugin system, multi-agent swarm, hook architecture, enhanced memory
• Opencode — Bash automation, file operations, safety hooks

Technologies

• Z.AI — GLM-5.1 model, Coding Plan API
• grammy — Telegram Bot Framework
• Vosk — Offline speech recognition
• node-edge-tts — Microsoft Edge TTS voices
• RTK — Rust Token Killer for token optimization
• Winston — Logging
• Express — Web server
• Systemd — 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
• Documentation: README.md, ARCHITECTURE.md
• Quick Start: QUICKSTART.md
• Installation: INSTALLATION.md (coming soon)
• API Docs: 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
Hermes Agent × Claude Code × Ruflo × Opencode