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, persistent self-learning memory, 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

### 🧠 Self-Learning Memory
- **Persistent across sessions**: JSON-backed memory store survives restarts
- **5 categories**: `lesson`, `pattern`, `preference`, `discovery`, `gotcha`
- **Auto-injected into system prompt**: AI knows what it learned before — every conversation builds on the last
- **Smart eviction**: Max 500 memories with priority-based eviction (old discoveries first, lessons/gotchas kept)
- **Deduplication**: Same memory won't be stored twice — access count increments instead

### 🔬 Curiosity Engine
The bot doesn't just respond — it **learns from every interaction**. After each response, an asynchronous analysis pass runs:

```
User message + AI response
         │
         ▼
   ┌─────────────────┐
   │ Pattern Detector │  ← runs AFTER delivery (zero latency)
   └────────┬────────┘
            │
    ┌───────┼───────┬──────────┬──────────┐
    ▼       ▼       ▼          ▼          ▼
  Error   User    Successful  First-time  New API
  + Fix   Correct  Complex     Tool       Quirk
    │      │      Solution     Usage      Found
    ▼      ▼       ▼           ▼          ▼
  gotcha  lesson  pattern   discovery  discovery
```

**What triggers learning:**
| Trigger | Category | Example |
|---|---|---|
| Error with fix found | `gotcha` | `ENOENT: no such file → use absolute paths` |
| User says "wrong" or "fix" | `lesson` | `Correction on "npm install": use --legacy-peer-deps` |
| Complex successful solution | `pattern` | `Solution for "deploy to VPS": 12-step process with SSH` |
| First tool usage works | `discovery` | `Bash tool works for shell commands on this server` |
| New API quirk discovered | `discovery` | `Z.AI SSE sends empty data lines between chunks` |
| Repeated user preference | `preference` | `User always wants TypeScript over JavaScript` |

**Commands:**
| Command | Description |
|---|---|
| `/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 |

### 🎤 Voice I/O (Speech-to-Text + Text-to-Speech)

Fully local voice processing. No API keys, no cloud services, no costs.

```
User sends voice message
         │
         ▼
  ┌──────────────┐
  │ Download OGG │  ← Telegram Bot API
  │ to /tmp      │
  └──────┬───────┘
         │
         ▼
  ┌──────────────┐
  │ ffmpeg → WAV │  ← 16kHz mono (Vosk requirement)
  │ (16kHz mono) │
  └──────┬───────┘
         │
         ▼
  ┌──────────────┐
  │ Vosk STT     │  ← Offline, ~200ms, 68MB model
  │ Python bridge│     Zero network calls
  └──────┬───────┘
         │
         ▼
  {"text": "...", "confidence": 0.95}
         │
         ▼
  Feed into chatWithAI → AI responds
  (optionally via TTS tool → voice reply)
```

| Component | Technology | Size | Latency | Cost |
|---|---|---|---|---|
| **STT** (voice→text) | [Vosk](https://alphacephei.com/vosk/) — offline speech recognition | 68MB model | ~200ms | Free |
| **TTS** (text→voice) | [node-edge-tts](https://github.com/yayuyokit/Edge-TTS-node) — Microsoft Edge voices | No download | ~2s | Free |
| **Audio conversion** | ffmpeg (system) | N/A | ~100ms | Free |

**How it works:**
1. Telegram sends voice as OGG Opus. Bot downloads to `/tmp`.
2. `scripts/stt.py` — Python bridge that converts to WAV (ffmpeg) and runs Vosk inference.
3. Returns JSON `{"text": "...", "confidence": 0.95}` to Node.js.
4. Transcribed text enters the normal `handleTextMessage()` pipeline — full AI response with streaming, tools, memory, self-correction.
5. AI can optionally use the `tts` tool to reply with a voice message.

**Why Vosk over Whisper:**
- **No GPU needed** — runs on CPU, ~200MB RAM (Whisper needs 1-4GB)
- **Fast** — 200ms vs 5-10s for Whisper on CPU
- **Tiny model** — 68MB vs 1-3GB for Whisper
- **Offline** — zero network calls, zero API costs
- **Good enough** — ~95% accuracy for English speech

### 🧬 Self-Evolution

zCode can **modify its own source code** — and survive the attempt. Every change goes through a safety chain that guarantees rollback on any failure.

**Safety chain (8 steps):**
```
AI requests patch
       │
       ▼
┌──────────────────┐
│ 1. Git stash     │  ← save uncommitted work
│ 2. Git commit    │  ← checkpoint current state
│ 3. File backup   │  ← copy original to .self-evolve-backups/
│ 4. Apply patch   │  ← string find/replace in target file
│ 5. Syntax check  │  ← node --check / py_compile / JSON.parse
│ 6. Git commit    │  ← commit the change
│ 7. Push + restart│  ← deploy to production
│ 8. Health + smoke│  ← verify bot is alive and responding
└──────────────────┘
       │
   ┌───┴───┐
   │ FAIL? │──── auto git reset + restart + restore from backup
   └───┬───┘
       │ OK
       ▼
   ✅ Live
```

**Protected files** — the bot **cannot** modify these (would brick itself):
- `SelfEvolveTool.js` — the safety system itself
- `stt.py` — voice recognition bridge

**Backup system:**
- Every `patch` auto-saves the original file to `.self-evolve-backups/` with a timestamp ID
- `backups` action lists all backups (file, size, timestamp)
- `restore` action copies any backup back to production (with its own safety checks)
- Backups survive git corruption — they're plain file copies, not git objects
- Restoring also creates a pre-restore backup (undo the undo)

**Actions:** `read`, `patch`, `list_files`, `git_log`, `diff`, `backups`, `restore`

**Rate limit:** 1 patch per 60 seconds (prevents runaway self-modification loops)

### 🧠 Intelligence Routing

The core of zCode CLI X's reliability. A unified agentic loop that handles both streaming and non-streaming through the same execution path — no more split paths that lose context or hang silently.

```
User Message
     │
     ▼
┌─────────────────────────────────────────┐
│         chatWithAI() — Main Loop        │
│  ┌───────────────────────────────────┐  │
│  │  Call API (stream or non-stream)  │  │
│  └─────────────┬─────────────────────┘  │
│                │                        │
│         ┌──────┴──────┐                 │
│         ▼             ▼                 │
│   tool_calls?     text content          │
│         │             │                 │
│    ┌────┴────┐    return answer         │
│    ▼         ▼                           │
│  Execute   Feed results                  │
│  tools     back to AI                    │
│    │         │                           │
│    └────┬────┘                           │
│         ▼                                │
│    Append to messages → loop back        │
│    (max 10 turns, forced final answer)   │
└─────────────────────────────────────────┘
```

**How it works:**

| Component | Role |
|---|---|
| `chatWithAI()` | Single entry point. While loop (max 10 turns) that calls API, handles tools, loops back. |
| `streamChat()` | SSE transport. Streams tokens to user via `onDelta()`. **Accumulates** tool_call deltas instead of aborting. Returns `{ content, tool_calls, error }`. |
| `nonStreamChat()` | REST transport. Single POST, returns `{ content, tool_calls, error }`. |
| Tool execution | Runs all tool_calls in parallel, appends results as `tool` messages, loops back. |

**Key design decisions:**
- **No recursive fallbacks.** Old code had stream → detect tool → abort → call non-stream (which lost the stream context). Now both paths return the same struct and feed into the same loop.
- **Tool call accumulation.** SSE sends tool_calls in delta chunks (name in one chunk, arguments in the next). `streamChat()` accumulates these across chunks and builds a complete `tool_calls` array — same as the non-streaming response.
- **Max 10 turns safety net.** If the AI keeps calling tools (infinite loop), after 10 turns a final non-streaming call without tools forces a text answer.
- **Streaming is transport, not logic.** Whether tokens stream to the user or not, the tool execution loop is identical.

**Before Intelligence Routing:**
```
Stream starts → detects tool_call → ABORT stream → recursive non-stream call
→ non-stream returns raw tool output as response → NO final answer from AI
→ user sees raw bash output or silence
```

**After Intelligence Routing:**
```
Stream starts → detects tool_call → accumulates full tool_call → executes tool
→ feeds result back to AI in same conversation → AI synthesizes final answer
→ streams final answer to user → done
```

### 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
- **⌨️ Persistent Typing Indicator**: `sendChatAction('typing')` every 4s
  - Active from message receipt through entire response (tool turns + streaming)
  - Telegram typing expires after ~5s — 4s interval keeps it alive continuously
  - Only stops when final response is fully delivered
  - Ensures user always sees activity, even during long tool execution gaps
- **🎨 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
- **🔁 Auto-Restart**: Process supervisor restarts the bot on crash (3s delay)
- **🛡️ 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
- **🛡️ Unhandled rejection guard**: Catches any async error that slips through

## 📦 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 --no-cli
```

### Run as systemd service (recommended)

```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 --no-cli
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable zcode
sudo systemctl start zcode
```

### Quick restart (no systemd)

```bash
bash restart.sh
```

## 🤖 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 |
| `/memory` | 🧠 Persistent memory stats |
| `/remember <text>` | 📝 Save to memory |
| `/recall <query>` | 🔍 Search memory |
| `/forget <id>` | 🗑 Delete a memory |
| `/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)  │
            └──────┬───────┘
                   │
                   ▼
            ┌──────────────┐
            │ 🧠 Self-     │  ← async, zero latency
            │ Learning     │     extracts patterns
            │ Engine       │     stores to memory.json
            └──────────────┘
```

### Core Components

```
zcode-cli-x/
├── bin/
│   └── zcode.js              # CLI entry point
├── src/
│   ├── bot/
│   │   ├── index.js          # Telegram bot (grammy + SSE streaming + memory)
│   │   ├── message-sender.js # StreamConsumer + markdownToHtml converter
│   │   ├── memory.js         # Persistent self-learning memory store
│   │   ├── 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
├── data/
│   └── memory.json           # Persistent memory (auto-created, gitignored)
├── logs/                     # Runtime logs (gitignored)
├── .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. **Memory Injection**: Memory context injected into system prompt
5. **Self-Correction**: `self-correction.js` (2 retries + exponential backoff + auto-simplification)
6. **AI Chat + Streaming**: `chatWithAI()` → SSE stream → `StreamConsumer` → real-time edits
7. **Formatting**: `markdownToHtml()` converts AI markdown → Telegram HTML
8. **Final Delivery**: `editMessageText` with HTML parse_mode (or fallback to stripped plain text)
9. **Self-Learning**: `selfLearn()` analyzes interaction → extracts patterns → saves to memory.json

### 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 **)
└──────────────┘
       │
       ▼ (async, after delivery)
┌──────────────┐
│ selfLearn()  │  ← pattern detector extracts learnable insights
│              │     saves to data/memory.json
└──────────────┘
```

### Memory System Architecture

```
┌──────────────────────────────────────────────┐
│              data/memory.json                │
│  (persistent, survives restarts, gitignored) │
└──────────────────┬───────────────────────────┘
                   │
         ┌─────────┴─────────┐
         │   MemoryStore     │
         │   (singleton)     │
         └─────────┬─────────┘
                   │
    ┌──────────────┼──────────────┬──────────────┬──────────────┐
    ▼              ▼              ▼              ▼              ▼
  📖 lesson    🔧 pattern    👤 preference  💡 discovery   ⚠️ gotcha
  "Always       "For deploy:  "User prefers   "Z.AI SSE      "ENOENT →
   use abs      use scp..."    TS over JS"     sends empty    use absolute
   paths"                                     data lines"     paths"
    │              │              │              │              │
    └──────────────┴──────────────┴──────────────┴──────────────┘
                   │
                   ▼
    buildContextSummary() → injected into system prompt
    recall(query) → search memories
    remember(cat, text) → save new memory
    forget(id) → delete memory
```

**Priority in system prompt:** gotchas > lessons > patterns > preferences > discoveries

**Eviction policy:** When memory exceeds 500 entries, old single-access discoveries are evicted first. Lessons and gotchas are never evicted unless all else fails.

## 🐝 zCode Swarm — Multi-Agent Orchestration

Distributed multi-agent coordination system inspired by [Ruflo](https://github.com/ruvnet/ruflo). Spawns specialized agent swarms that work in parallel — code reviews, security audits, performance analysis, architecture validation, test orchestration, and git operations.

### Architecture

```
        ┌─────────────────────┐
        │  SwarmOrchestrator  │
        │  (main entry point) │
        └─────────┬───────────┘
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
┌────────┐  ┌──────────┐  ┌──────────┐
│Neural  │  │Federated │  │Agent     │
│Network │  │Memory    │  │Market-   │
│(ML)    │  │(6 NS)    │  │place     │
└────────┘  └──────────┘  └──────────┘
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Hiera-    │ │ Mesh +   │ │ Gossip + │
│rchical   │ │ CRDT     │ │ Consensus│
│Queen     │ │ P2P      │ │ BFT      │
└──────────┘ └──────────┘ └──────────┘
                  │
    ┌─────┬─────┬─┴────┬──────┬──────┐
    ▼     ▼     ▼      ▼      ▼      ▼
  Code  Perf  Sec   Arch   Test   Git
 Review Opt   Audit Analy  Orch   Swarm
```

### 6 Agent Skills

| Skill | ID | What It Does |
|---|---|---|
| 🔍 Code Review | `code-review-swarm` | Multi-agent review: security, performance, style, architecture |
| ⚡ Performance | `performance-optimizer` | Bottleneck detection, N+1 queries, memory leaks, score calculation |
| 🔒 Security | `security-auditor` | Injection, XSS, auth, data leakage — severity classification |
| 🏗️ Architecture | `architecture-analyzer` | Coupling/cohesion analysis, SOLID compliance scoring |
| 🧪 Testing | `test-orchestrator` | Test generation, coverage analysis, execution tracking |
| 🔄 Git | `git-swarm` | Multi-repo PR analysis, review, branch management |

### 4 Coordination Modes

| Mode | Pattern | Best For |
|---|---|---|
| **Hierarchical** | Queen-led | Default — single decision-maker routes tasks |
| **Mesh** | P2P + CRDT | Decentralized teams, conflict-free replication |
| **Gossip** | Random propagation | Large networks, eventual consistency |
| **Consensus** | Byzantine fault-tolerant | Critical decisions, 10% fault tolerance |

### Advanced Features

- **🧠 Neural Network Integration** — ML-based agent recommendation with confidence scoring and real-time learning
- **📦 Agent Marketplace** — Plugin discovery, install/uninstall, capability-based search
- **📊 Real-Time Dashboard** — Terminal monitoring with 5s refresh, performance scores, memory stats
- **📈 Performance Metrics** — CPU/memory tracking, trend analysis, automated recommendations
- **🧩 Federated Memory** — 6 namespaces (coordination, project-context, patterns, knowledge, session, metrics)

### Quick Start

```bash
# Verify installation (22 files)
node verify-swarm.cjs

# Run demo
node quick-start.cjs

# Configure
vim .zcode/config/coordinator.yaml
```

### Configuration (`.zcode/config/coordinator.yaml`)

```yaml
coordination:
  mode: hierarchical  # hierarchical | mesh | gossip | consensus

agents:
  enabled:
    - code-review-swarm
    - performance-optimizer
    - security-auditor
    - architecture-analyzer
    - test-orchestrator
    - git-swarm

neural:
  enabled: true
  architecture: multi-layer-perceptron
  layers: [64, 32, 16, 8]

dashboard:
  enabled: false  # true for live terminal dashboard

marketplace:
  enabled: true
```

## 📊 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 | ✅ zCode Swarm (6 skills, 4 modes, ML) | ✅ delegate_task + batch | ❌ Single agent only |
| Agent roles | ✅ Reviewer, Architect, DevOps, Security, Tester, Git | ✅ Agent Registry (10+ roles) | ❌ Fixed single role |
| Neural coordination | ✅ ML agent recommendation | ❌ Rule-based only | ❌ None |
| Agent marketplace | ✅ Plugin discovery + install | ❌ Manual skills | ❌ None |
| Federated memory | ✅ 6-namespace CRDT-backed | ✅ Cross-session memory | ❌ None |
| Self-correction loops | ✅ 2 retries + backoff + auto-simplification | ✅ Agent self-correction skill | ❌ None |
| **Intelligence** | | | |
| Persistent memory | ✅ JSON-backed, 5 categories, auto-learn | ✅ Cross-session memory | ❌ None |
| Self-learning / curiosity | ✅ Pattern detector + auto-extraction | ✅ Knowledge + memory tools | ❌ None |
| Memory-injected prompts | ✅ Every conversation uses past lessons | ✅ Memory injected | ❌ None |
| **Streaming** | | | |
| Intelligence Routing | ✅ Unified agentic loop (stream+non-stream) | ⚠️ Separate stream/non-stream paths | ❌ None |
| Real-time SSE streaming | ✅ StreamConsumer (edit-in-place) | ✅ GatewayStreamConsumer | ❌ None |
| Tool call accumulation | ✅ Delta accumulation from SSE chunks | ⚠️ Abort on tool detection | ❌ 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 ||
|| Persistent typing indicator | ✅ 4s interval, active during full response | ❌ None | ❌ None ||
|| Discord | ✅ Native bot (discord.js) | ✅ Full Discord integration | ❌ None ||
| Multi-channel delivery | ✅ Delivery hub (TG + DC + WS + log) | ✅ Cron→multi-platform | ❌ None |
|| **Voice** | | | |
|| Speech-to-Text | ✅ Vosk (offline, ~200ms, 68MB) | ⚠️ Whisper (needs GPU) | ❌ None |
|| Text-to-Speech | ✅ Edge TTS (free, 100+ voices) | ✅ node-edge-tts | ❌ None |
|| Voice→AI pipeline | ✅ Transcribe → full agentic loop | ⚠️ Separate pipeline | ❌ None |
|| **Self-Evolution** | | | |
|| Self-modifying code | ✅ Patch own source + auto-deploy | ❌ Not supported | ❌ None |
|| Auto-backup before change | ✅ File-level + git checkpoint | N/A | N/A |
|| Auto-rollback on failure | ✅ Syntax + health + smoke test | N/A | N/A |
|| Backup history + restore | ✅ Timestamped backups, 1-command restore | N/A | N/A |
|| **Infrastructure** | | | |
| Model routing | ✅ Multi-provider | ✅ Multi-provider routing | ❌ Single model |
| Context compression | ✅ Compact pipeline | ✅ lean-ctx MCP (90% savings) | ❌ None |
| Auto-restart | ✅ Process supervisor | ✅ systemd managed | ❌ None |
| Cron scheduling | ✅ 1s interval, jitter, locks | ✅ Cron jobs with delivery | ❌ None |

### Summary

- **zCode CLI X** — Lightweight agentic coder focused on Telegram + Z.AI. **Intelligence Routing** — a unified agentic loop that handles streaming and non-streaming through one execution path with tool call accumulation from SSE deltas. Real-time SSE streaming, self-correction loops, persistent self-learning memory with curiosity engine, RTK optimization, and beautiful HTML formatting. **zCode Swarm** — distributed multi-agent orchestration with 6 specialized skills (code review, security, performance, architecture, testing, git), 4 coordination modes (hierarchical, mesh, gossip, consensus), neural network-based agent recommendation, federated memory, agent marketplace, and real-time dashboard. Gets smarter with every conversation. 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 + sequentialize + 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)
- **Vosk**: Offline speech recognition (STT, 68MB model, no API key)
- **ffmpeg**: Audio conversion (OGG → WAV for Vosk)
- **zCode Swarm**: Multi-agent orchestration (`.zcode/` directory)

## 🤝 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 + memory system credit)

---

Built with ⚡ by zCode CLI X