zCode-CLI-X/README.md

# 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](https://z.ai/subscribe?ic=ROK78RJKNW) for the Coding Plan

## 🚀 Features

- **🤖 AI-Powered Code Generation**: Powered by Z.AI GLM-5.1 (Coding Plan)
- **📱 Telegram Bot**: 24/7 live interaction via Telegram
- **🛠️ 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

## 📦 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=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

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

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

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

### Run in Development Mode

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

### Run Only CLI (No Bot)

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

## 🤖 Telegram Bot

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

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

## 🛠️ 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/
├── bin/
│   └── zcode.js              # CLI entry point
├── src/
│   ├── api/
│   │   └── index.js          # Z.AI API adapter
│   ├── bot/
│   │   └── index.js          # Telegram bot integration
│   ├── tools/
│   │   ├── BashTool.js       # Shell command executor
│   │   ├── FileEditTool.js   # File operations
│   │   ├── WebSearchTool.js  # Web search
│   │   └── GitTool.js        # Git operations
│   ├── skills/
│   │   └── index.js          # Skills system
│   ├── agents/
│   │   └── index.js          # Agent orchestration
│   └── utils/
│       ├── logger.js         # Winston logger
│       └── env.js            # Environment validation
├── .env                      # Configuration
└── package.json
```

## 🔗 Integrations

- **Z.AI API**: GLM-5.1 model with Coding Plan
- **Telegram Bot API**: Webhook + WebSocket
- **Express.js**: HTTP server
- **Winston**: Logging

## 🚀 Getting Started

1. Install dependencies:
   ```bash
   npm install
   ```

2. Configure `.env` with your credentials

3. Run the bot:
   ```bash
   node bin/zcode.js --bot
   ```

4. Open Telegram and 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 | ❌ None | ✅ Full Discord integration | ❌ None |
| Multi-channel delivery | ❌ Telegram only | ✅ Cron→Telegram/Discord/Email | ❌ None |
| Voice I/O | ✅ Voice service (STT + TTS) | ✅ TTS + voice memos | ❌ 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](https://github.com/x1xhlol/better-clawd.git) - Claude Code clone
- [Hermes Agent](https://hermes-agent.nousresearch.com) - Our AI assistant

---

Built with ❤️ by zCode CLI X