zCode CLI X

Agentic coder with Z.AI + Telegram integration — Claude Code + Hermes in one beast.

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

🚀 Features

• 🤖 AI-Powered Code Generation: Powered by Z.AI GLM-5.1 (Coding Plan)
• 📱 Multi-Channel Bot: Telegram + Discord with real-time delivery
• 🛠️ Full Engineering Access: Bash, FileEdit, WebSearch, Git tools
• 🧠 Agent System: Code reviewer, architect, DevOps engineer
• 📚 Skills System: Pre-built skills for common tasks
• ⚡ Real-time Updates: WebSocket-based live communication
• 🔄 Self-Correction: Automatic retry with backoff (2 retries)
• 📦 Multi-Channel Delivery: Hub-based message routing (Telegram + Discord + WebSocket + log)

📦 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=your_z...here

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_b...here
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 in Development Mode

node bin/zcode.js --dev

Run Only CLI (No Bot)

node bin/zcode.js --no-bot

🤖 Telegram & Discord Bot

Once running, you can interact with zCode CLI X via multiple channels:

Telegram

1. Start the bot: /start
2. Send your code requests or questions
3. Receive AI-powered responses in real-time

Discord

1. Invite the bot to your server
2. Send commands or questions
3. Receive responses with full streaming support

Multi-Channel Delivery

Messages are automatically delivered to:

• ✅ Telegram (primary)
• ✅ Discord
• ✅ WebSocket (real-time)
• ✅ Log file (structured)

🛠️ Tools Available

• Bash: Execute shell commands
• FileEdit: Edit files with diff-aware operations
• WebSearch: Search the web for information
• Git: Git operations (status, log, branch)

🧠 Agents

• Code Reviewer: Review code for bugs and improvements
• System Architect: Design system architecture and patterns
• DevOps Engineer: Handle deployment, CI/CD, and infrastructure

📚 Skills

• code_review: Review code for bugs, security issues, and improvements
• bug_fix: Fix identified bugs in code
• refactor: Refactor code for better quality
• documentation: Generate and update documentation
• testing: Write tests for code

🏗️ Architecture

zCode CLI X uses a hybrid architecture combining:

• better-clawd: Coding backbone (BashTool, FileEditTool, WebSearchTool, GitTool)
• Hermes Agent: Agent system (Code Reviewer, Architect, DevOps)
• claudegram: Bot patterns (grammy, deduplication, request queuing, multi-channel delivery)

Core Components

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

Bot Flow

1. Message Reception: Telegram/Discord messages → delivery-hub.js
2. Deduplication Check: deduplication.js (60s TTL)
3. Request Queue: request-queue.js (per-chat sequential processing)
4. Self-Correction: self-correction.js (2 retries + backoff)
5. Agent Execution: better-clawd tools + Hermes agents
6. Response Delivery: message-sender.js → Multi-channel (Telegram + Discord + WebSocket + log)

Provider Support

• Z.AI: GLM-5.1 (Coding Plan) - Primary
• Claude: Anthropic Claude (via API)
• OpenCode: OpenCode CLI integration
• Kilo: Kilo.AI gateway

🔗 Integrations

• Z.AI API: GLM-5.1 model with Coding Plan
• Telegram Bot API: grammy-based bot with auto-retry and runner
• Discord.js v14: Discord bot with GatewayIntentBits
• Express.js: HTTP server for webhook handling
• Winston: Structured logging
• WebSocket: Real-time updates
• Mongoose: Database persistence
• Puppeteer: Browser automation

🚀 Getting Started

1. Install dependencies:

   npm install
   

2. Configure .env with your credentials:

   GLM_BASE_URL=https://api.z.ai/api/coding/paas/v4
   ZAI_API_KEY=your_zai_api_key
   TELEGRAM_BOT_TOKEN=your_telegram_bot_token
   TELEGRAM_ALLOWED_USERS=your_telegram_user_id
   DISCORD_TOKEN=your_discord_bot_token
   

3. Run the bot:

   node bin/zcode.js --bot
   

4. Open Telegram and Discord to start chatting!

📝 License

MIT

📊 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	❌ None	✅ Agent self-correction skill	❌ None
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	✅ GitTool	❌ None
Browser automation	✅ Computer-use (Anthropic)	✅ Full browser toolkit	❌ None
MCP servers	✅ Full MCP protocol (client + server management)	✅ Native MCP + mcporter	❌ None
Code execution	✅ Sandbox adapter	✅ Sandbox + Jupyter	❌ None
Skills
Skill system	✅ Skill system with skills dir loader	✅ 500+ skills catalog	❌ No skill system
Custom skill authoring	✅ Skillify (session→skill capture)	✅ skill_manage CLI	❌ None
Plugin architecture	✅ Full marketplace + loader + lifecycle	✅ Full plugin system	❌ None
Automation
Cron scheduling	✅ CronScheduler (1s interval, jitter, locks)	✅ Cron jobs with delivery	❌ None
Webhook subscriptions	✅ Hook system (HTTP, agent, prompt hooks)	✅ Event-driven agent runs	❌ None
Scheduled monitoring	✅ Cron-based recurring monitoring	✅ Browser + social monitors	❌ None
Batch task processing	✅ Batch skill (5-30 parallel subagents)	✅ Parallel batch delegation	❌ None
Platform
Telegram integration	✅ Native bot + webhook	✅ 2-way Telegram bridge	❌ None
Discord	✅ Native bot (via discord.js)	✅ Full Discord integration	❌ None
Multi-channel delivery	✅ Delivery hub (Telegram + Discord + WebSocket + log)	✅ Cron→Telegram/Discord/Email	❌ None
Self-correction loops	✅ Self-correction wrapper (2 retries + backoff)	✅ Agent self-correction skill	❌ None
Infrastructure
Model routing	✅ Multi-provider (OpenAI, Anthropic, Bedrock, custom)	✅ Multi-provider routing	❌ Single model
Context compression	✅ Compact pipeline (auto, micro, session memory)	✅ lean-ctx MCP (90% savings)	❌ None
Memory persistence	✅ Session memory with background extraction	✅ Cross-session memory	❌ None
RTK integration	✅ RTK active	✅ RTK integrated	❌ None

Summary

• zCode CLI X — Lightweight agentic coder focused on Telegram + Z.AI. Ideal for quick coding tasks via Telegram with essential tools and agent roles.
• Hermes Agent — Full-stack AI assistant platform. Best for complex multi-agent workflows, scheduled automation, and cross-platform deployment. 500+ skills, MCP ecosystem, and the deepest toolset.
• better-clawd — Minimal Claude Code clone. Useful as a lightweight reference but lacks the agentic, skills, and automation depth of zCode or Hermes.

🤝 Contributing

Contributions welcome! This is based on:

• better-clawd - Claude Code clone
• Hermes Agent - Our AI assistant

---

Built with ❤️ by zCode CLI X