zCode-CLI-X/README.md

# 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](https://z.ai/subscribe?ic=ROK78RJKNW) 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](https://github.com/nousresearch/hermes-agent)
  - 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

```bash
cd zcode-cli-x
npm install
```

## ⚙️ Configuration

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

### Required Environment Variables

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

```bash
node bin/zcode.js
```

### Run as Telegram Bot (24/7)

```bash
node bin/zcode.js --bot
```

### Run as systemd service

```ini
# /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
```

```bash
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](https://github.com/x1xhlol/better-clawd.git) — Claude Code clone
- [Hermes Agent](https://hermes-agent.nousresearch.com) — AI assistant platform (streaming architecture credit)

---

Built with ⚡ by zCode CLI X