admin/zCode-CLI-X
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c63a1c03ae3aab15e02c9a5f632a814485000ec1
zCode-CLI-X/README.md

14 KiB
Raw Blame History

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:

Built with ⚡ by zCode CLI X

Reference in New Issue View Git Blame Copy Permalink