98ed33ba8f
Root cause: fuser-based EADDRINUSE handler killed the current process due to a race condition during systemd restart cycles. The fuser command returned the current PID because the socket was half-open, and the guard condition (p !== process.pid) failed to filter it. Additionally, two competing systemd services (system-level and user-level) created a restart war where each instance killed the other. Fix approach (inspired by Next.js, Vite, webpack-dev-server): - Replace fuser with net.createServer port probe (no external commands) - PID-file based stale detection + ss fallback for orphan detection - Wait loop with 300ms polling after SIGTERM to stale process - Single-service architecture (disabled user-level unit) Tested: 5 consecutive rapid restarts, 8+ minute uptime, zero crashes. Co-Authored-By: zcode <noreply@zcode.dev>
677 lines
26 KiB
Markdown
677 lines
26 KiB
Markdown
# zCode CLI X
|
||
|
||
<div align="center">
|
||
|
||
**The Ultimate Agentic Coding Assistant**
|
||
*Hermes Agent × Claude Code × Ruflo × Opencode — All in One*
|
||
|
||
[](https://nodejs.org)
|
||
[](LICENSE)
|
||
[](https://github.rommark.dev/admin/zCode-CLI-X)
|
||
|
||
**Get 10% OFF Z.AI** — Use code `ROK78RJKNW` at [z.ai/subscribe](https://z.ai/subscribe?ic=ROK78RJKNW)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 🚀 Overview
|
||
|
||
zCode CLI X is a **24/7 autonomous coding agent** that combines the best of:
|
||
|
||
- ✅ **Hermes Agent** — Telegram bot with self-learning, voice I/O, RTK optimization
|
||
- ✅ **Claude Code** — Unified agentic loop, tool call accumulation, SSE streaming
|
||
- ✅ **Ruflo** — Plugin extensibility, multi-agent swarm, hook system, enhanced memory
|
||
- ✅ **Opencode** — Bash/file/git automation with safety hooks
|
||
|
||
Running as a **systemd service** with **self-evolution capabilities** and **bulletproof rollback**.
|
||
|
||
> **v2.0.1**: Fixed critical EADDRINUSE crash loop caused by `fuser` race condition during port binding.
|
||
> Replaced with kernel-level port probing (`net.createServer` + `ss` fallback). Zero crash restarts.
|
||
> See [CHANGELOG](CHANGELOG.md) for full details.
|
||
|
||
---
|
||
|
||
## ⚡ Core Features
|
||
|
||
### 🤖 AI-Powered Code Generation
|
||
- Powered by **Z.AI GLM-5.1** (Coding Plan)
|
||
- Real-time SSE streaming with token-by-token delivery
|
||
- Automatic self-correction loops with exponential backoff
|
||
- Max 10-turn safety net to prevent infinite tool loops
|
||
|
||
### 📱 Telegram Bot (24/7)
|
||
- **grammy** framework with webhook + WebSocket
|
||
- Real-time token streaming with adaptive backoff on 429 errors
|
||
- Persistent typing indicator (refreshes every 4s)
|
||
- HTML formatting with double fallback (HTML → plain text)
|
||
- **Voice I/O** — Vosk STT (offline) + node-edge-tts TTS (voice cloning ready)
|
||
|
||
### 🧠 Self-Learning Memory
|
||
- **Persistent across sessions** — JSON-backed memory survives restarts
|
||
- **5 categories**: `lesson`, `pattern`, `preference`, `discovery`, `gotcha`
|
||
- **Auto-injected into system prompt** — AI remembers what it learned
|
||
- **Smart eviction** — Max 500 memories with priority-based eviction
|
||
- **Deduplication** — Same memory won't be stored twice
|
||
- **Curiosity Engine** — Asynchronous pattern detection after every response
|
||
|
||
### 🧬 Self-Evolution
|
||
- **Modify its own source code** with 3-layer safety:
|
||
1. Git stash + checkpoint commit
|
||
2. File-level backups to `.self-evolve-backups/`
|
||
3. Syntax check → health check → smoke test before declaring success
|
||
- **Automatic rollback** on any failure
|
||
- **Protected files** — Cannot modify `SelfEvolveTool.js`, `stt.py`
|
||
- **Rate limited** — 1 patch per 60 seconds
|
||
|
||
### 🧠 Intelligence Routing
|
||
- **Unified agentic loop** — Same execution path for streaming + non-streaming
|
||
- **Tool call accumulation** — Collects tool calls from SSE deltas (no context loss)
|
||
- **No recursive fallbacks** — Both paths return same struct, feed into same loop
|
||
- **Max 10 turns safety net** — Forces final text answer after 10 tool turns
|
||
|
||
### 🛠️ Engineering Tools (18 Total)
|
||
- **BashTool** — Full shell access with security hooks (1,143 lines of safety logic)
|
||
- **FileEditTool** — Diff-aware editing with heredoc fallback
|
||
- **FileReadTool** — LRU cache + read-once dedup
|
||
- **FileWriteTool** — JSON-safe content with heredoc fallback
|
||
- **GitTool** — Commit, push, PR creation with destructive command protection
|
||
- **WebSearchTool** — DuckDuckGo API
|
||
- **WebFetchTool** — HTTP fetch with cheerio parsing
|
||
- **BrowserTool** — Headless browser automation
|
||
- **VisionTool** — Image analysis via Z.AI
|
||
- **TTSTool** — Text-to-speech via Microsoft Edge
|
||
- **GrepTool** — Ripgrep-backed search
|
||
- **GlobTool** — File pattern matching
|
||
- **TaskCreateTool** — Task management
|
||
- **TaskUpdateTool** — Update task status
|
||
- **TaskListTool** — List all tasks
|
||
- **SendMessageTool** — Send messages to channels
|
||
- **ScheduleCronTool** — Cron scheduler with task locking
|
||
- **SelfEvolveTool** — Self-modification with rollback
|
||
|
||
### 🎯 Agent System (9 Built-in Roles)
|
||
- **Coder** — Implementation, debugging, refactoring
|
||
- **Tester** — Unit tests, integration tests, E2E
|
||
- **Reviewer** — Code review, security audit, best practices
|
||
- **Architect** — System design, patterns, scalability
|
||
- **DevOps** — Deployment, CI/CD, infrastructure
|
||
- **Security** — Vulnerability scanning, penetration testing
|
||
- **Researcher** — Documentation, API research, competitive analysis
|
||
- **Designer** — UI/UX, design systems, accessibility
|
||
- **Coordinator** — Task orchestration, dependency management
|
||
|
||
### 🦋 Multi-Agent Swarm
|
||
- **SwarmCoordinator** — Orchestrate 3 topologies:
|
||
- `simple` — Linear execution
|
||
- `hierarchical` — Manager-worker pattern
|
||
- `swarm` — Peer-to-peer collaboration
|
||
- **6 New Tools**:
|
||
- `swarm_spawn` — Spawn new agent swarm
|
||
- `swarm_execute` — Execute current task
|
||
- `swarm_distribute` — Distribute work to agents
|
||
- `swarm_state` — Check swarm status
|
||
- `swarm_terminate` — Terminate all agents
|
||
- `delegate_agent` — Delegate task to specific agent
|
||
|
||
### 🔌 Plugin System (Ruflo-Inspired)
|
||
- **PluginManager** — Fault-isolated extension point routing with metrics
|
||
- **PluginLoader** — Dependency-resolving batch loader
|
||
- **ExtensionPoints** — 16 standard extension points:
|
||
- `tool.execute` — Before/after tool execution
|
||
- `ai.response` — Before/after AI response
|
||
- `session.start` / `session.end` — Session lifecycle
|
||
- `message.receive` / `message.send` — Message routing
|
||
- `memory.save` / `memory.load` — Memory persistence
|
||
- `agent.spawn` / `agent.terminate` — Agent lifecycle
|
||
- `cron.trigger` — Cron job execution
|
||
- `health.check` — Health check endpoint
|
||
- And more...
|
||
- **BasePlugin** — Lifecycle hooks (initialize, shutdown)
|
||
|
||
### 🪝 Hook System (Ruflo-Inspired)
|
||
- **Pre/Post Tool Hooks** — Log, validate, cache before/after tool execution
|
||
- **Pre/Post AI Hooks** — Modify prompts, analyze responses, track metrics
|
||
- **Session Lifecycle Hooks** — On start, on end, on pause, on resume
|
||
- **Priority-based execution** — Ordered hook execution
|
||
- **Zero latency impact** — Runs asynchronously after main response
|
||
|
||
### 💾 Enhanced Memory Backend (Ruflo-Inspired)
|
||
- **JSONBackend** — Typed entries, LRU eviction, text search
|
||
- **InMemoryBackend** — Ephemeral agent context with TTL auto-eviction
|
||
- **Memory Types**:
|
||
- `lesson` — User corrections, best practices
|
||
- `pattern` — Successful complex solutions
|
||
- `preference` — User preferences (language, style, tools)
|
||
- `discovery` — API quirks, tool capabilities, new patterns
|
||
- `gotcha` — Errors + fixes
|
||
- `context` — Session context, temporary state
|
||
- `ephemeral` — Agent-specific temporary data
|
||
|
||
### ⚡ Performance & Reliability
|
||
- **RTK (Rust Token Killer)** — 60-90% token savings on git, npm, cargo, pytest, docker
|
||
- **Request Queue** — Per-chat sequential processing (no race conditions)
|
||
- **Deduplication** — 60s TTL message deduplication
|
||
- **Auto-Restart** — systemd supervisor restarts on crash
|
||
- **Unhandled Rejection Guard** — Catches any async error
|
||
- **Health Checks** — `/health` endpoint + smoke tests
|
||
|
||
---
|
||
|
||
## 📦 Installation
|
||
|
||
### Prerequisites
|
||
- **Node.js** ≥ 20.0.0
|
||
- **npm** or **yarn**
|
||
- **ffmpeg** (for voice I/O)
|
||
- **Python 3.8+** (for Vosk STT)
|
||
- **systemd** (for 24/7 service)
|
||
|
||
### Quick Start
|
||
|
||
```bash
|
||
# Clone repository
|
||
git clone https://github.rommark.dev/admin/zCode-CLI-X.git
|
||
cd zCode-CLI-X
|
||
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Configure environment
|
||
cp .env.example .env
|
||
nano .env # Edit with your credentials
|
||
|
||
# Start as CLI (temporary)
|
||
node bin/zcode.js
|
||
|
||
# Start as Telegram bot (24/7)
|
||
node bin/zcode.js --no-cli
|
||
|
||
# Install as systemd service (recommended)
|
||
cp scripts/zcode.service ~/.config/systemd/user/
|
||
systemctl --user daemon-reload
|
||
systemctl --user enable zcode
|
||
systemctl --user start zcode
|
||
|
||
# Check status
|
||
systemctl --user status zcode
|
||
|
||
# View logs
|
||
journalctl --user -u zcode -f
|
||
```
|
||
|
||
### Full Installation Guide
|
||
|
||
See [INSTALLATION.md](./INSTALLATION.md) for:
|
||
- Detailed environment setup
|
||
- Voice I/O configuration (Vosk + ffmpeg)
|
||
- Telegram webhook setup
|
||
- SSL/HTTPS configuration
|
||
- Custom domain setup
|
||
- Docker deployment (coming soon)
|
||
|
||
---
|
||
|
||
## ⚙️ Configuration
|
||
|
||
### Environment Variables
|
||
|
||
```env
|
||
# Z.AI Configuration (Coding Plan)
|
||
GLM_BASE_URL=https://api.z.ai/api/coding/paas/v4
|
||
ZAI_API_KEY=your_zai_api_key
|
||
|
||
# Telegram Bot Configuration
|
||
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
|
||
TELEGRAM_ALLOWED_USERS=your_telegram_id,friend_id
|
||
ZCODE_WEBHOOK_URL=https://your-domain.com/telegram/webhook
|
||
|
||
# Optional: Voice I/O
|
||
VOSK_MODEL_PATH=/path/to/vosk-model-small
|
||
FFMPEG_PATH=/usr/bin/ffmpeg
|
||
|
||
# Optional: RTK (Rust Token Killer)
|
||
RTK_PATH=~/.local/bin/rtk
|
||
|
||
# Optional: Logging
|
||
LOG_LEVEL=info # debug, info, warn, error
|
||
LOG_FILE=logs/zcode.log
|
||
```
|
||
|
||
### Config File
|
||
|
||
```json
|
||
// .zcode.config.json
|
||
{
|
||
"api": {
|
||
"baseUrl": "https://api.z.ai/api/coding/paas/v4",
|
||
"models": {
|
||
"default": "glm-5.1",
|
||
"fallback": "glm-4v"
|
||
}
|
||
},
|
||
"telegram": {
|
||
"allowedUsers": ["123456789"],
|
||
"webhookUrl": "https://your-domain.com/telegram/webhook"
|
||
},
|
||
"memory": {
|
||
"maxEntries": 500,
|
||
"evictionPolicy": "lru"
|
||
},
|
||
"agents": {
|
||
"enabled": ["coder", "reviewer", "architect"],
|
||
"maxTurns": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎮 Usage
|
||
|
||
### Telegram Commands
|
||
|
||
#### Core Commands
|
||
```
|
||
/start — Welcome message + feature overview
|
||
/help — Full command list
|
||
/tools — List all available tools
|
||
/skills — List all available skills
|
||
/agents — List all available agent roles
|
||
/model — Switch AI model (glm-5.1, glm-4v, etc.)
|
||
/stats — Show performance metrics (RTK savings, memory size)
|
||
/voice — Toggle voice I/O mode
|
||
/mcp — Manage MCP servers
|
||
/memory — View memory stats + recent memories
|
||
/cron — Cron job management
|
||
/cancel — Cancel current task
|
||
/selfcorrection — Toggle auto self-correction
|
||
```
|
||
|
||
#### Memory Commands
|
||
```
|
||
/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
|
||
```
|
||
|
||
#### Swarm Commands (Multi-Agent)
|
||
```
|
||
/swarm_spawn coder,reviewer,tester — "Build a React app"
|
||
/swarm_state — Check swarm progress
|
||
/swarm_execute — Run current task
|
||
/swarm_distribute — Distribute work to agents
|
||
/swarm_terminate — Stop all agents
|
||
```
|
||
|
||
#### Self-Evolve Commands
|
||
```
|
||
/self_evolve action=read file=src/bot/index.js
|
||
/self_evolve action=patch file=src/bot/index.js old_code="..." new_code="..." message="Fix bug"
|
||
/self_evolve action=list_files
|
||
/self_evolve action=git_log
|
||
/self_evolve action=diff file=src/bot/index.js
|
||
/self_evolve action=backups — List all backups
|
||
/self_evolve action=restore backup_id=2026-05-05T18-30-00 file=src/bot/index.js
|
||
```
|
||
|
||
### CLI Usage
|
||
|
||
```bash
|
||
# Run as CLI (temporary session)
|
||
node bin/zcode.js
|
||
|
||
# Run with specific model
|
||
node bin/zcode.js --model glm-4v
|
||
|
||
# Run with dev mode (hot reload)
|
||
npm run dev
|
||
|
||
# Run as bot (24/7)
|
||
node bin/zcode.js --no-cli
|
||
|
||
# Run with specific config
|
||
node bin/zcode.js --config .zcode.config.json
|
||
```
|
||
|
||
---
|
||
|
||
## 🏗️ Architecture
|
||
|
||
### System Overview
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ zCode CLI X │
|
||
│ Hermes Agent × Claude Code × Ruflo × Opencode │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌───────────────────┼───────────────────┐
|
||
│ │ │
|
||
┌───▼────┐ ┌─────▼────┐ ┌─────▼────┐
|
||
│ CLI │ │ Bot │ │ Agent │
|
||
│ Mode │ │ Mode │ │ System │
|
||
└───┬────┘ └─────┬────┘ └─────┬────┘
|
||
│ │ │
|
||
└───────────────────┼───────────────────┘
|
||
│
|
||
┌───────────────────┼───────────────────┐
|
||
│ │ │
|
||
┌───▼────┐ ┌─────▼────┐ ┌─────▼────┐
|
||
│ Tools │ │ Skills │ │ Agents │
|
||
│ │ │ │ │ │
|
||
│ Bash │ │ Code │ │ Coder │
|
||
│ File │ │ Review │ │ Architect│
|
||
│ Web │ │ Bug Fix │ │ DevOps │
|
||
│ Git │ │ Refactor │ │ Tester │
|
||
│ ... │ │ ... │ │ Reviewer │
|
||
└───┬────┘ └─────┬────┘ └─────┬────┘
|
||
│ │ │
|
||
└───────────────────┼───────────────────┘
|
||
│
|
||
┌───────────────────┼───────────────────┐
|
||
│ │ │
|
||
┌───▼────┐ ┌─────▼────┐ ┌─────▼────┐
|
||
│ Z.AI │ │ Telegram │ │ File │
|
||
│ API │ │ API │ │ System │
|
||
│ │ │ │ │ │
|
||
│ GLM-5.1│ │ Webhook │ │ Express │
|
||
│ Coding │ │ WS │ │ Node.js │
|
||
│ │ │ Bot │ │ File I/O │
|
||
└────────┘ └──────────┘ └──────────┘
|
||
```
|
||
|
||
### Ruflo Integration Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Ruflo Systems │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Plugin │ │ Hook │ │ Swarm │ │
|
||
│ │ Manager │ │ Manager │ │ Coordinator │ │
|
||
│ │ │ │ │ │ │ │
|
||
│ │ 16 Extension │ │ Pre/Post │ │ 3 Topologies │ │
|
||
│ │ Points │ │ Tool/AI │ │ 9 Agent Roles│ │
|
||
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
||
│ │ │ │ │
|
||
│ └─────────────────┼─────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────▼────────┐ │
|
||
│ │ Memory Backend │ │
|
||
│ │ (JSON + LRU) │ │
|
||
│ └─────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Message Flow
|
||
|
||
```
|
||
User (Telegram) → Webhook → Bot → Intent Detection
|
||
↓
|
||
┌─────────────────────┐
|
||
│ Pre-Tool Hooks │
|
||
└──────────┬──────────┘
|
||
↓
|
||
┌─────────────────────┐
|
||
│ Tool Execution │
|
||
│ (Bash, File, Git) │
|
||
└──────────┬──────────┘
|
||
↓
|
||
┌─────────────────────┐
|
||
│ Post-Tool Hooks │
|
||
└──────────┬──────────┘
|
||
↓
|
||
┌─────────────────────┐
|
||
│ AI Response (Z.AI) │
|
||
│ (SSE Streaming) │
|
||
└──────────┬──────────┘
|
||
↓
|
||
┌─────────────────────┐
|
||
│ Post-AI Hooks │
|
||
│ (Curiosity Engine) │
|
||
└──────────┬──────────┘
|
||
↓
|
||
┌─────────────────────┐
|
||
│ Self-Learning │
|
||
│ (Memory Update) │
|
||
└──────────┬──────────┘
|
||
↓
|
||
┌─────────────────────┐
|
||
│ Stream to User │
|
||
│ (HTML Formatted) │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Feature Comparison
|
||
|
||
| Feature | zCode CLI X | Hermes Agent | Claude Code | Ruflo | Opencode |
|
||
|---------|-------------|--------------|-------------|-------|----------|
|
||
| **24/7 Telegram Bot** | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||
| **Self-Learning Memory** | ✅ | ✅ | ❌ | ✅ | ❌ |
|
||
| **Voice I/O (STT/TTS)** | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||
| **RTK Token Optimization** | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||
| **Self-Evolution** | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||
| **Unified Agentic Loop** | ✅ | ⚠️ | ✅ | ❌ | ✅ |
|
||
| **SSE Streaming** | ✅ | ✅ | ✅ | ❌ | ✅ |
|
||
| **Tool Call Accumulation** | ✅ | ❌ | ✅ | ❌ | ✅ |
|
||
| **Multi-Agent Swarm** | ✅ | ❌ | ❌ | ✅ | ❌ |
|
||
| **Plugin System** | ✅ | ❌ | ❌ | ✅ | ❌ |
|
||
| **Hook System** | ✅ | ❌ | ❌ | ✅ | ❌ |
|
||
| **Enhanced Memory Backend** | ✅ | ⚠️ | ❌ | ✅ | ❌ |
|
||
| **18 Tools** | ✅ | 12 | 15 | N/A | 20+ |
|
||
| **9 Agent Roles** | ✅ | 3 | N/A | 9 | N/A |
|
||
| **16 Extension Points** | ✅ | N/A | N/A | 16 | N/A |
|
||
| **Cron Scheduler** | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
| **Git Integration** | ✅ | ✅ | ✅ | ❌ | ✅ |
|
||
| **Bash Automation** | ✅ | ✅ | ✅ | ❌ | ✅ |
|
||
| **File Operations** | ✅ | ✅ | ✅ | ❌ | ✅ |
|
||
| **Web Scraping** | ✅ | ✅ | ❌ | ❌ | ✅ |
|
||
| **Browser Automation** | ✅ | ✅ | ❌ | ❌ | ✅ |
|
||
| **Vision (Image Analysis)** | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||
| **TTS (Voice Reply)** | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||
| **Bulletproof Rollback** | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||
| **Protected Files** | ✅ | ❌ | ❌ | ❌ | ❌ |
|
||
| **Rate Limiting** | ✅ | ⚠️ | ⚠️ | ✅ | ⚠️ |
|
||
| **Health Checks** | ✅ | ✅ | ❌ | ✅ | ✅ |
|
||
| **Documentation** | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
|
||
**Legend**: ✅ Full support | ⚠️ Partial support | ❌ Not available
|
||
|
||
---
|
||
|
||
## 🎯 Use Cases
|
||
|
||
### 1. **Autonomous Development**
|
||
- Build full-stack apps from scratch
|
||
- Refactor legacy codebases
|
||
- Write tests, docs, and deployment configs
|
||
- Self-correct when errors occur
|
||
|
||
### 2. **Code Review & Security**
|
||
- Automated code review with 9 agent roles
|
||
- Security vulnerability scanning
|
||
- Best practices enforcement
|
||
- Performance optimization suggestions
|
||
|
||
### 3. **DevOps & Deployment**
|
||
- CI/CD pipeline configuration
|
||
- Docker/Kubernetes setup
|
||
- Infrastructure as Code (Terraform, Pulumi)
|
||
- Monitoring and alerting setup
|
||
|
||
### 4. **Data Analysis & Research**
|
||
- Web scraping with browser automation
|
||
- API research and integration
|
||
- Competitive analysis
|
||
- Documentation generation
|
||
|
||
### 5. **Voice-First Interaction**
|
||
- Talk to your coding agent
|
||
- Get voice responses
|
||
- Hands-free development
|
||
- Accessibility support
|
||
|
||
### 6. **Multi-Agent Collaboration**
|
||
- Spawn swarms for complex tasks
|
||
- Distribute work across specialized agents
|
||
- Hierarchical task orchestration
|
||
- Peer-to-peer agent collaboration
|
||
|
||
---
|
||
|
||
## 🔒 Security
|
||
|
||
### Self-Evolution Safety
|
||
- **Protected files** — Cannot modify `SelfEvolveTool.js`, `stt.py`
|
||
- **Rate limiting** — 1 patch per 60 seconds
|
||
- **File size limit** — Max 80KB per edit
|
||
- **3-layer rollback** — Git stash → backup → health check
|
||
- **Automatic verification** — Syntax check + smoke test before declaring success
|
||
|
||
### Tool Security
|
||
- **Destructive command protection** — Git push --force, rm -rf, etc.
|
||
- **Permission validation** — All tools require explicit permission
|
||
- **Sandboxing** — Bash tool runs with restricted capabilities
|
||
- **Security hooks** — Pre/post tool validation
|
||
- **Audit logging** — All tool calls logged to `logs/zcode.log`
|
||
|
||
### Data Privacy
|
||
- **No external data collection** — All processing local
|
||
- **Encrypted storage** — `.env` file not committed
|
||
- **Memory isolation** — Per-chat conversation context
|
||
- **No telemetry** — Zero analytics, zero tracking
|
||
|
||
---
|
||
|
||
## 📈 Performance
|
||
|
||
### Benchmarks
|
||
- **Startup time**: ~10 seconds
|
||
- **Memory usage**: 54.5M (peak 56.2M)
|
||
- **Voice STT**: ~200ms (Vosk, offline)
|
||
- **Voice TTS**: ~2s (node-edge-tts)
|
||
- **RTK savings**: 60-90% on git, npm, cargo, pytest, docker
|
||
- **Token optimization**: 40-60% with prompt compression
|
||
|
||
### Scalability
|
||
- **Concurrent chats**: 50+ (per instance)
|
||
- **Message queue**: Unlimited (per-chat sequential processing)
|
||
- **Memory**: 500 entries max (LRU eviction)
|
||
- **Tool calls**: 10 turns max per conversation (safety net)
|
||
|
||
---
|
||
|
||
## 🤝 Contributing
|
||
|
||
We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
|
||
- Development setup
|
||
- Coding standards
|
||
- Pull request process
|
||
- Feature proposal guidelines
|
||
|
||
### Quick Start for Contributors
|
||
```bash
|
||
# Clone repository
|
||
git clone https://github.rommark.dev/admin/zCode-CLI-X.git
|
||
cd zCode-CLI-X
|
||
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Run in dev mode (hot reload)
|
||
npm run dev
|
||
|
||
# Run smoke tests
|
||
node test-ruflo-smoke.mjs
|
||
|
||
# Commit changes
|
||
git commit -m "feat: add new feature"
|
||
git push origin main
|
||
```
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT License — See [LICENSE](./LICENSE) for details.
|
||
|
||
---
|
||
|
||
## 🙏 Credits & Acknowledgments
|
||
|
||
### Core Projects
|
||
- **[Hermes Agent](https://github.com/nousresearch/hermes-agent)** — Telegram bot framework, stream consumer, RTK integration
|
||
- **[Claude Code](https://github.com/anthropics/claude-code)** — Unified agentic loop, tool call accumulation, SSE streaming
|
||
- **[Ruflo](https://github.com/ruvnet/ruflo)** — Plugin system, multi-agent swarm, hook architecture, enhanced memory
|
||
- **[Opencode](https://github.com/opencode/opencode)** — Bash automation, file operations, safety hooks
|
||
|
||
### Technologies
|
||
- **[Z.AI](https://z.ai)** — GLM-5.1 model, Coding Plan API
|
||
- **[grammy](https://grammy.dev)** — Telegram Bot Framework
|
||
- **[Vosk](https://alphacephei.com/vosk/)** — Offline speech recognition
|
||
- **[node-edge-tts](https://github.com/yayuyokit/Edge-TTS-node)** — Microsoft Edge TTS voices
|
||
- **[RTK](https://github.com/rtk-ai/rtk)** — Rust Token Killer for token optimization
|
||
- **[Winston](https://github.com/winstonjs/winston)** — Logging
|
||
- **[Express](https://expressjs.com)** — Web server
|
||
- **[Systemd](https://systemd.io)** — Process supervisor
|
||
|
||
### Special Thanks
|
||
- **NousResearch** — Hermes Agent team for Telegram bot patterns
|
||
- **Anthropic** — Claude Code for agentic loop architecture
|
||
- **RuvNet** — Ruflo team for plugin/swarm/hook systems
|
||
- **Community contributors** — All PRs, issues, and feedback
|
||
|
||
---
|
||
|
||
## 📞 Support & Contact
|
||
|
||
- **Issues**: [GitHub Issues](https://github.rommark.dev/admin/zCode-CLI-X/issues)
|
||
- **Documentation**: [README.md](./README.md), [ARCHITECTURE.md](./ARCHITECTURE.md)
|
||
- **Quick Start**: [QUICKSTART.md](./QUICKSTART.md)
|
||
- **Installation**: [INSTALLATION.md](./INSTALLATION.md) (coming soon)
|
||
- **API Docs**: [API.md](./API.md) (coming soon)
|
||
|
||
---
|
||
|
||
## 🚀 Roadmap
|
||
|
||
### v1.1 (Q2 2026)
|
||
- [ ] Docker deployment support
|
||
- [ ] MCP server auto-discovery
|
||
- [ ] Voice cloning (ElevenLabs/XTTS v2)
|
||
- [ ] Enhanced swarm topologies (federated, gossip)
|
||
- [ ] Plugin marketplace
|
||
|
||
### v1.2 (Q3 2026)
|
||
- [ ] Web UI dashboard
|
||
- [ ] Multi-language support (Spanish, French, German)
|
||
- [ ] Advanced analytics dashboard
|
||
- [ ] Custom agent training (LoRA fine-tuning)
|
||
- [ ] API rate limiting & quotas
|
||
|
||
### v2.0 (Q4 2026)
|
||
- [ ] Kubernetes deployment
|
||
- [ ] Horizontal scaling (multiple instances)
|
||
- [ ] Distributed memory backend (Redis)
|
||
- [ ] Plugin hot-reload (no restart needed)
|
||
- [ ] Agent marketplace (share/swarm agents)
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**Built with ⚡ by [Roman](https://twitter.com/uroma2)**
|
||
*Hermes Agent × Claude Code × Ruflo × Opencode*
|
||
|
||
[](https://github.rommark.dev/admin/zCode-CLI-X)
|
||
[](https://t.me/your_bot_username)
|
||
[](LICENSE)
|
||
|
||
</div>
|