zCode CLI X

Agentic coding assistant with Z.AI + Telegram integration — autonomous code execution with real-time streaming, self-correction loops, persistent self-learning memory, 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

🧠 Self-Learning Memory

• Persistent across sessions: JSON-backed memory store survives restarts
• 5 categories: lesson, pattern, preference, discovery, gotcha
• Auto-injected into system prompt: AI knows what it learned before — every conversation builds on the last
• Smart eviction: Max 500 memories with priority-based eviction (old discoveries first, lessons/gotchas kept)
• Deduplication: Same memory won't be stored twice — access count increments instead

🔬 Curiosity Engine

The bot doesn't just respond — it learns from every interaction. After each response, an asynchronous analysis pass runs:

User message + AI response
         │
         ▼
   ┌─────────────────┐
   │ Pattern Detector │  ← runs AFTER delivery (zero latency)
   └────────┬────────┘
            │
    ┌───────┼───────┬──────────┬──────────┐
    ▼       ▼       ▼          ▼          ▼
  Error   User    Successful  First-time  New API
  + Fix   Correct  Complex     Tool       Quirk
    │      │      Solution     Usage      Found
    ▼      ▼       ▼           ▼          ▼
  gotcha  lesson  pattern   discovery  discovery

What triggers learning:

Trigger	Category	Example
Error with fix found	gotcha	ENOENT: no such file → use absolute paths
User says "wrong" or "fix"	lesson	Correction on "npm install": use --legacy-peer-deps
Complex successful solution	pattern	Solution for "deploy to VPS": 12-step process with SSH
First tool usage works	discovery	Bash tool works for shell commands on this server
New API quirk discovered	discovery	Z.AI SSE sends empty data lines between chunks
Repeated user preference	preference	User always wants TypeScript over JavaScript

Commands:

Command	Description
/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

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
• 🔁 Auto-Restart: Process supervisor restarts the bot on crash (3s delay)
• 🛡️ 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
• 🛡️ Unhandled rejection guard: Catches any async error that slips through

📦 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 --no-cli

Run as systemd service (recommended)

# /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 --no-cli
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable zcode
sudo systemctl start zcode

Quick restart (no systemd)

bash restart.sh

🤖 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
/memory	🧠 Persistent memory stats
/remember <text>	📝 Save to memory
/recall <query>	🔍 Search memory
/forget <id>	🗑 Delete a memory
/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)  │
            └──────┬───────┘
                   │
                   ▼
            ┌──────────────┐
            │ 🧠 Self-     │  ← async, zero latency
            │ Learning     │     extracts patterns
            │ Engine       │     stores to memory.json
            └──────────────┘

Core Components

zcode-cli-x/
├── bin/
│   └── zcode.js              # CLI entry point
├── src/
│   ├── bot/
│   │   ├── index.js          # Telegram bot (grammy + SSE streaming + memory)
│   │   ├── message-sender.js # StreamConsumer + markdownToHtml converter
│   │   ├── memory.js         # Persistent self-learning memory store
│   │   ├── 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
├── data/
│   └── memory.json           # Persistent memory (auto-created, gitignored)
├── logs/                     # Runtime logs (gitignored)
├── .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. Memory Injection: Memory context injected into system prompt
5. Self-Correction: self-correction.js (2 retries + exponential backoff + auto-simplification)
6. AI Chat + Streaming: chatWithAI() → SSE stream → StreamConsumer → real-time edits
7. Formatting: markdownToHtml() converts AI markdown → Telegram HTML
8. Final Delivery: editMessageText with HTML parse_mode (or fallback to stripped plain text)
9. Self-Learning: selfLearn() analyzes interaction → extracts patterns → saves to memory.json

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 **)
└──────────────┘
       │
       ▼ (async, after delivery)
┌──────────────┐
│ selfLearn()  │  ← pattern detector extracts learnable insights
│              │     saves to data/memory.json
└──────────────┘

Memory System Architecture

┌──────────────────────────────────────────────┐
│              data/memory.json                │
│  (persistent, survives restarts, gitignored) │
└──────────────────┬───────────────────────────┘
                   │
         ┌─────────┴─────────┐
         │   MemoryStore     │
         │   (singleton)     │
         └─────────┬─────────┘
                   │
    ┌──────────────┼──────────────┬──────────────┬──────────────┐
    ▼              ▼              ▼              ▼              ▼
  📖 lesson    🔧 pattern    👤 preference  💡 discovery   ⚠️ gotcha
  "Always       "For deploy:  "User prefers   "Z.AI SSE      "ENOENT →
   use abs      use scp..."    TS over JS"     sends empty    use absolute
   paths"                                     data lines"     paths"
    │              │              │              │              │
    └──────────────┴──────────────┴──────────────┴──────────────┘
                   │
                   ▼
    buildContextSummary() → injected into system prompt
    recall(query) → search memories
    remember(cat, text) → save new memory
    forget(id) → delete memory

Priority in system prompt: gotchas > lessons > patterns > preferences > discoveries

Eviction policy: When memory exceeds 500 entries, old single-access discoveries are evicted first. Lessons and gotchas are never evicted unless all else fails.

📊 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
Intelligence
Persistent memory	✅ JSON-backed, 5 categories, auto-learn	✅ Cross-session memory	❌ None
Self-learning / curiosity	✅ Pattern detector + auto-extraction	✅ Knowledge + memory tools	❌ None
Memory-injected prompts	✅ Every conversation uses past lessons	✅ Memory injected	❌ 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
Auto-restart	✅ Process supervisor	✅ systemd managed	❌ 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, persistent self-learning memory with curiosity engine, RTK optimization, and beautiful HTML formatting. Gets smarter with every conversation. 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 + sequentialize + 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 + memory system credit)

---

Built with ⚡ by zCode CLI X