zCode CLI X

Agentic coding assistant with Z.AI + Telegram integration — autonomous code execution with real-time streaming, self-correction loops, and RTK token optimization.

💡 Get 10% OFF Z.AI — Use code ROK78RJKNW at z.ai/subscribe for the Coding Plan

⚡ Features

Core

• 🤖 AI-Powered Code Generation: Powered by Z.AI GLM-5.1 (Coding Plan)
• 📱 Telegram Bot: 24/7 via grammy + webhook with real-time SSE streaming
• 🛠️ Full Engineering Access: Bash, FileEdit, WebSearch, Git tools
• 🧠 Agent System: Code Reviewer, System Architect, DevOps Engineer
• 📚 Skills System: Pre-built skills for common tasks

Streaming & Formatting

• ⚡ Real-time SSE Streaming: Token-by-token delivery via StreamConsumer — adapted from Hermes Agent's GatewayStreamConsumer
  • Queued token buffer → rate-limited editMessageText loop (1s base interval)
  • Adaptive backoff on Telegram flood control (429)
  • Typing cursor ▉ during generation, clean final message
  • Graceful fallback to plain send on repeated failures
• 🎨 Telegram HTML Formatting: AI markdown → clean Telegram HTML
  • **bold**, *italic*, `code`, fenced code blocks, [links](url), ~~strike~~, headings, blockquotes, lists
  • Double fallback: HTML → stripped plain text (never shows raw **)

Reliability

• 🔄 Self-Correction Loops: Automatic retry with exponential backoff
  • 2 retry attempts (500ms → 1s → 1.5s delay)
  • Triggers: API errors, rate limits, timeouts, 5xx server errors
  • Auto-simplification: prompts simplified on retry to avoid recurring errors
  • Full logging of all retry attempts with reason tracking
• 🛡️ RTK (Rust Token Killer): Token optimization for supported commands
  • 60-90% savings on git, npm, cargo, pytest, docker, and more
  • Active tracking stats via getTrackingStats()

Architecture

• 📨 Multi-Channel Delivery: Hub-based routing (Telegram + Discord + WebSocket + log)
• 🔁 Deduplication: 60s TTL message deduplication
• 📋 Request Queue: Per-chat sequential processing (no race conditions)
• 🔌 MCP Protocol: Full MCP client + server management
• ⏰ Cron Scheduling: 1s interval, task locking, auto-recovery

📦 Installation

cd zcode-cli-x
npm install

⚙️ Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Required Environment Variables

# Z.AI Configuration (Coding Plan)
GLM_BASE_URL=https://api.z.ai/api/coding/paas/v4
ZAI_API_KEY=***

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=***
TELEGRAM_ALLOWED_USERS=your_telegram_id
ZCODE_WEBHOOK_URL=https://your-domain.com/telegram/webhook

🎮 Usage

Run as CLI

node bin/zcode.js

Run as Telegram Bot (24/7)

node bin/zcode.js --bot

Run as systemd service

# /etc/systemd/system/zcode.service
[Unit]
Description=zCode CLI X Bot
After=network.target

[Service]
Type=simple
User=<your-user>
WorkingDirectory=/path/to/zcode-cli-x
ExecStart=/usr/bin/node bin/zcode.js --bot
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable zcode
sudo systemctl start zcode

🤖 Telegram Bot Commands

Command	Description
/start	Show help and capabilities
/tools	List available tools
/skills	List loaded skills
/agents	List agent roles
/model <name>	Switch AI model
/stats	System & RTK stats
/selfcorrection	Self-correction status
/bash <cmd>	Execute shell command
/web <query>	Search the web
/git <action>	Git operations
/cancel	Cancel current operation

Or just chat — zCode uses tools automatically when needed.

🛠️ Tools

Tool	Description
BashTool	Shell command execution with timeout control
FileEditTool	Diff-aware file operations (read, write, patch)
WebSearchTool	Web search with result ranking
GitTool	Git operations (status, log, diff, commit, push, pull)

🧠 Agents

Agent	Role
Code Reviewer	Review code for bugs, security issues, and improvements
System Architect	Design system architecture and patterns
DevOps Engineer	Handle deployment, CI/CD, and infrastructure

🏗️ Architecture

zCode CLI X uses a hybrid architecture:

User Message
    │
    ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Telegram    │────▶│ dedup.js     │────▶│ request-queue   │
│  (grammy)    │     │ (60s TTL)    │     │ (per-chat seq)  │
└─────────────┘     └──────────────┘     └────────┬────────┘
                                                   │
                                                   ▼
                                          ┌────────────────┐
                                          │ self-correction │
                                          │ (2 retries +   │
                                          │  backoff)       │
                                          └────────┬───────┘
                                                   │
                              ┌────────────────────┼────────────────────┐
                              ▼                    ▼                    ▼
                     ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
                     │ chatWithAI   │    │ Tool         │    │ Agent        │
                     │ (SSE stream) │    │ Handlers     │    │ Delegation   │
                     └──────┬───────┘    └──────────────┘    └──────────────┘
                            │
                    ┌───────┴────────┐
                    ▼                ▼
            ┌──────────────┐ ┌──────────────┐
            │ Stream       │ │ sendFormatted│
            │ Consumer     │ │ (HTML mode)  │
            │ (edit-in-    │ └──────────────┘
            │  place)      │
            └──────┬───────┘
                   │
                   ▼
            ┌──────────────┐
            │ markdown     │
            │ ToHtml()     │
            │ converter    │
            └──────┬───────┘
                   │
                   ▼
            ┌──────────────┐
            │ Telegram API │
            │ (HTML mode)  │
            └──────────────┘

Core Components

zcode-cli-x/
├── bin/
│   └── zcode.js              # CLI entry point
├── src/
│   ├── bot/
│   │   ├── index.js          # Telegram bot (grammy + SSE streaming)
│   │   ├── message-sender.js # StreamConsumer + markdownToHtml converter
│   │   ├── deduplication.js  # Message deduplication (60s TTL)
│   │   ├── request-queue.js  # Per-chat request queuing
│   │   ├── delivery-hub.js   # Multi-channel delivery
│   │   ├── discord.js        # Discord integration (discord.js v14)
│   │   └── self-correction.js # Self-correction wrapper (2 retries + backoff)
│   ├── api/
│   │   └── index.js          # Z.AI API adapter (GLM-5.1, SSE support)
│   ├── tools/
│   │   ├── BashTool.js       # Shell command executor (RTK-aware)
│   │   ├── FileEditTool.js   # File operations
│   │   ├── WebSearchTool.js  # Web search
│   │   └── GitTool.js        # Git operations (RTK-aware)
│   ├── agents/
│   │   └── index.js          # Agent orchestration
│   ├── skills/
│   │   └── index.js          # Skills system
│   └── utils/
│       ├── logger.js         # Winston logger
│       ├── env.js            # Environment validation
│       └── rtk.js            # RTK (Rust Token Killer) integration
├── .env                      # Configuration
└── package.json

Bot Message Flow

1. Message Reception: Telegram webhook → grammy handler
2. Deduplication: deduplication.js (60s TTL, prevents double-processing)
3. Request Queue: request-queue.js (per-chat sequential processing)
4. Self-Correction: self-correction.js (2 retries + exponential backoff + auto-simplification)
5. AI Chat + Streaming: chatWithAI() → SSE stream → StreamConsumer → real-time edits
6. Formatting: markdownToHtml() converts AI markdown → Telegram HTML
7. Final Delivery: editMessageText with HTML parse_mode (or fallback to stripped plain text)

StreamConsumer Pipeline

Z.AI API (SSE)
    │
    ▼ onDelta(token)
┌──────────────┐
│ Token Buffer │  ← accumulates tokens from SSE stream
└──────┬───────┘
       │ (every ~1s or 40 chars)
       ▼
┌──────────────┐
│ editMessage  │  ← plain text + cursor ▉ (no parse_mode)
│ Text()       │     rate-limited, adaptive backoff on flood
└──────┬───────┘
       │ (on finish)
       ▼
┌──────────────┐
│ markdownTo   │  ← converts **bold**, *italic*, `code`, etc.
│ Html()       │     to <b>, <i>, <code>, <pre> HTML tags
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ editMessage  │  ← final message with parse_mode: 'HTML'
│ Text()       │     fallback: stripped plain text (no raw **)
└──────────────┘

📊 Feature Comparison

Feature	zCode CLI X	Hermes Agent	better-clawd
Agentic
Autonomous execution	✅ Full autonomous mode	✅ Full autonomous mode	⚠️ Manual step-by-step
Sub-agents	✅ Multi-agent (swarm)	✅ delegate_task + batch	❌ Single agent only
Agent roles	✅ Code Reviewer, Architect, DevOps	✅ Agent Registry (10+ roles)	❌ Fixed single role
Self-correction loops	✅ 2 retries + backoff + auto-simplification	✅ Agent self-correction skill	❌ None
Streaming
Real-time SSE streaming	✅ StreamConsumer (edit-in-place)	✅ GatewayStreamConsumer	❌ None
Telegram HTML formatting	✅ markdownToHtml + fallback	✅ Native HTML support	❌ None
Adaptive flood control	✅ Exponential backoff	✅ Flood backoff	❌ N/A
Tooling
Bash/Shell	✅ BashTool	✅ TerminalTool	✅ Shell access
File editing	✅ FileEditTool (diff-aware)	✅ Patch + Write + Edit	⚠️ Basic write
Web search	✅ WebSearch	✅ WebSearch + Vane + Exa	❌ None
Git integration	✅ GitTool (RTK-aware)	✅ GitTool	❌ None
Browser automation	✅ Computer-use (Anthropic)	✅ Full browser toolkit	❌ None
MCP servers	✅ Full MCP protocol	✅ Native MCP + mcporter	❌ None
RTK optimization	✅ RTK active (60-90% savings)	✅ RTK integrated	❌ None
Platform
Telegram integration	✅ Native bot + webhook + streaming	✅ 2-way Telegram bridge	❌ None
Discord	✅ Native bot (discord.js)	✅ Full Discord integration	❌ None
Multi-channel delivery	✅ Delivery hub (TG + DC + WS + log)	✅ Cron→multi-platform	❌ None
Infrastructure
Model routing	✅ Multi-provider	✅ Multi-provider routing	❌ Single model
Context compression	✅ Compact pipeline	✅ lean-ctx MCP (90% savings)	❌ None
Memory persistence	✅ Session memory	✅ Cross-session memory	❌ None
Cron scheduling	✅ 1s interval, jitter, locks	✅ Cron jobs with delivery	❌ None

Summary

• zCode CLI X — Lightweight agentic coder focused on Telegram + Z.AI. Real-time SSE streaming, self-correction loops, RTK optimization, and beautiful HTML formatting. Ideal for quick coding tasks via Telegram.
• Hermes Agent — Full-stack AI assistant platform. Best for complex multi-agent workflows, scheduled automation, and cross-platform deployment. 500+ skills, MCP ecosystem, deepest toolset.
• better-clawd — Minimal Claude Code clone. Useful as a lightweight reference but lacks agentic depth.

🔗 Integrations

• Z.AI API: GLM-5.1 model (Coding Plan) with SSE streaming
• Telegram Bot API: grammy + auto-retry + runner + webhook
• Discord.js v14: Discord bot with GatewayIntentBits
• Express.js: HTTP server for webhook handling
• Winston: Structured logging
• WebSocket: Real-time updates
• RTK: Rust Token Killer (token optimization)

🤝 Contributing

Contributions welcome! Based on:

• better-clawd — Claude Code clone
• Hermes Agent — AI assistant platform (streaming architecture credit)

---

Built with ⚡ by zCode CLI X