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

260 lines
9.4 KiB
Markdown
Raw Blame History

# 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)
- **📱 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
```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 & 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:
```bash
npm install
```
2. Configure `.env` with your credentials:
```env
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:
```bash
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](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
Reference in New Issue View Git Blame Copy Permalink