Helyx

Helyx

[](LICENSE) [](https://github.com/MrCipherSmith/helyx/actions) [](https://bun.sh) [](https://www.typescriptlang.org)

[Dashboard](examples/dashboard.md) | [Usage Patterns](examples/usage-patterns.md) | [Architecture](guides/architecture.md) | [Cloudflare Tunnel](guides/cloudflare-tunnel-setup.md) | [Remote Laptop Setup](guides/remote-laptop-setup.md) | [Usage Scenarios](guides/usage-scenarios.md) | [Memory](guides/memory.md) | [MCP Tools](guides/mcp-tools.md) | [Shared MCP Services](guides/shared-mcp-services.md) | [Mini App](guides/webapp.md) | [Voice Conversations](guides/voice.md) | [Interactive Polls](guides/polls.md) | [Codex Review](guides/codex.md) | [CLAUDE.md Guide](CLAUDEMDGUIDE.md)

> Control Claude Code from Telegram. Each project gets its own topic in a Telegram Forum group — no /switch needed. Persistent sessions, dual-layer memory, voice transcription, image analysis, and real-time CLI progress monitoring.

Connect multiple Claude Code CLI instances to a single Telegram bot. Each project lives in its own forum topic — open the topic, type normally, Claude replies there. Status updates and permission requests appear in the correct topic. No context bleeding, no /switch ceremony.

Quick Start

curl -fsSL https://raw.githubusercontent.com/MrCipherSmith/helyx/main/install.sh | bash

The installer checks prerequisites, clones the repo, installs dependencies, sets up the helyx CLI, and launches the setup wizard.

Then connect any project:

cd your-project && helyx connect . --tmux

Done. Open Telegram, run /forum_setup in your group — your projects appear as topics.

Forum Group Setup

The recommended way to use Helyx is with a Telegram Forum Supergroup where each project gets its own topic.

Step 1 — Create a Supergroup

1. In Telegram tap New Group → add yourself → set a name (e.g. 🧠 Dev Hub)
2. Open group Settings → Group type → Topics → enable
3. The group becomes a Forum Supergroup with a General topic

Step 2 — Add the bot as admin

1. Open group ⋮ → Manage Group → Administrators → Add Admin
2. Search your bot (e.g. @helyx_grace_bot)
3. Enable Manage Topics permission
4. Save

Step 3 — Run /forum_setup

Open the General topic and send:

/forum_setup

The bot will:

• Verify the group has Topics enabled
• Save the group chat ID to bot_config
• Create one topic per registered project (keryx, helyx, vantage-frontend, …)
• Pin a Dev Hub button in General topic (opens the Mini App WebApp)
• Reply: ✅ Forum configured. N topics created.

Topics appear in the left sidebar immediately.

Step 4 — Start working

Open any project topic and type normally:

keryx topic:  "add a test for the auth middleware"
              → Claude replies here, status shows here, permissions appear here

No /switch ever needed. The topic IS the project.

Daily use

| Action | How | |--------|-----| | Talk to keryx | Open keryx topic, type normally | | Talk to helyx | Open helyx topic, type normally | | Check all projects | /projects in General topic | | Add new project | /project_add /path/to/project — topic auto-created | | Re-sync topics | /forum_sync in General topic |

Topic management

/topic_rename    — rename the current topic
/topic_close           — close (pause) topic
/topic_reopen          — reopen topic
/forum_sync            — create missing topics, re-sync

Backward compatibility

If you don't run /forum_setup, the bot works exactly as before — private DM, /switch routing, everything unchanged. Forum mode is additive.

Dashboard

See all dashboard pages: [Overview, Sessions, Stats, Logs, Memory](examples/dashboard.md)

Why MCP?

This bot is a full Model Context Protocol server. Claude Code CLI connects to it via MCP — the same protocol used by VS Code, Cursor, and other AI tools.

What this means:

• Any Claude Code instance (terminal, VS Code, SSH) can connect and receive Telegram messages
• The bot exposes MCP tools: reply, remember, recall, update_status — Claude uses them like native capabilities
• Permission requests flow through MCP channel protocol — approve Bash/Read/Edit from your phone
• Multiple CLIs share the same memory and session state through the MCP server

For agent builders: This bot can serve as a human-in-the-loop interface for any MCP-compatible agent system. Send tasks from Telegram, approve actions, monitor progress.

Features

Core

• Multi-Session MCP Server — multiple Claude Code CLI instances connect via HTTP, each as a named session
• Session Switching — /switch between CLI sessions and standalone mode, with context summary and last messages
• One Session Per Project — reconnecting CLIs reuse existing sessions, preserving ID and memory
• Channel Adapter — stdio bridge that forwards Telegram messages to Claude Code as channel notifications, with lease-based session ownership (TTL lease in DB, auto-expires on crash), and graceful shutdown on stdin close
• Auto-Named Sessions — CLI sessions automatically named after the project directory, with source labels (tmux/cli)

AI & Media

• Standalone Mode — bot responds directly via LLM API (Anthropic / Google AI / OpenRouter / Ollama) with automatic retry on 429/5xx
• Codex Code Review — OpenAI Codex CLI integration for AI-powered code review; authenticate headlessly via /codex_setup (device flow, no terminal needed); trigger via /codex_review or natural language ("review my code"); falls back to Claude's native review on quota/auth errors; model configurable via CODEX_MODEL env var
• Voice Messages — transcription via Groq whisper-large-v3 with local Whisper as offline fallback; voice replies via Yandex SpeechKit → Piper (local) → Kokoro-82M (local) → Groq
• Interactive Polls — Claude can ask clarifying questions as native Telegram polls (send_poll MCP tool); you tap answers, press Submit ✅, and results flow back automatically as a user message; supports forum topic routing, 24h expiry, and vote retraction
• Image Analysis — photos analyzed by Claude in CLI sessions; standalone mode with Anthropic API
• File Forwarding — photos, documents, and videos forwarded to Claude via MCP with base64 (≤5 MB images) or file path; if sent without caption, bot asks what to do before forwarding
• Auto-Summarization — idle conversations are summarized to long-term memory after 15 min

Skills Toolkit — v1.35.0

• Inline Shell Expansion — SKILL.md bodies can embed ` !cmd tokens that resolve to shell output at load time, eliminating one tool-call round-trip per dynamic dependency. Sandboxed: explicit env allowlist (no process.env inheritance — !echo $DEEPSEEKAPIKEY cannot leak secrets), 5 s timeout with SIGTERM → 500 ms grace → SIGKILL fallback, 4096-char output cap, concurrent pipe drain. Demo: skills/git-state/SKILL.md`.
• Autonomous Skill Creator — after a multi-step success, the agent can distill the workflow into a reusable SKILL.md via aux-LLM (DeepSeek default; Ollama / OpenRouter fallback). The proposed skill arrives in Telegram with a [Save] / [Reject] / [Edit name…] keyboard; on approval it's persisted to agent_created_skills in postgres and atomically materialized to ~/.claude/skills/agent-created//SKILL.md for Claude Code's native loader.
• Skill Curator — weekly cron (Sundays 03:00 UTC, configurable) reviews agent_created_skills: auto-pins frequently-used (use_count > 10, last 14 days), auto-archives stale (>90 days idle), queues consolidate/patch proposals for human approval ([Approve] / [Skip], 24 h expiry). Aux-LLM is fully isolated — Anthropic prompt cache for the main session is never touched. Cost is logged per run in aux_llm_invocations.
• Observability — every preprocessor invocation, distillation, and curator run is logged to postgres (skill_preprocess_log, aux_llm_invocations, curator_runs, curator_pending_actions).

Session Lifecycle

• Persistent Projects — projects table as single source of truth; added via /project_add (bot) or helyx add (CLI) — both write to the same DB; helyx up reads from DB directly
• Remote Sessions — one persistent session per project (source=remote), started/stopped from bot or terminal; status: 🟢 active / ⚪ inactive
• Local Sessions — temporary, multiple per project, live while Claude process runs; on exit: work summary generated and archived; deletable from Telegram bot (/sessions) or dashboard
• Work Summary on Exit — AI-optimized structured summary ([DECISIONS][FILES][PROBLEMS][PENDING][CONTEXT]) vectorized and saved to long-term memory; raw messages archived with TTL
• Switch Briefing — switching to a session shows its last project-context summary and injects it as system context for the next message

Memory

• Short-Term — sliding window of recent messages per session (in-memory cache + PostgreSQL)
• Long-Term — semantic search via pgvector embeddings powered by Ollama (nomic-embed-text, 768 dims)
• Smart Reconciliation — /remember and work summaries use LLM-based deduplication: new facts are compared against similar existing memories and the system decides ADD / UPDATE / DELETE / NOOP instead of always inserting
• Project-Scoped — memories and project context shared across all sessions in the same project
• Cross-Session History — new CLI sessions automatically load prior conversation context from previous sessions in the same project
• Auto-Summarization — remote session conversations summarized on idle/overflow; messages archived with configurable TTL (default 30 days)

Telegram UX

• Forum Topics — each project gets its own topic in a Telegram Forum Supergroup; messages, status updates, and permission requests are scoped to the correct topic; General topic is control-only; /forum_setup creates all topics at once; /project_add auto-creates a topic for new projects
• Markdown Rendering — responses formatted with HTML (bold, italic, code blocks with syntax highlighting, links)
• Live Status Updates — real-time progress from CLI via tmux monitoring ("Explore: Find files", "Bash: git status"); status appears in the project topic in forum mode
• Permission Forwarding — CLI permission requests as inline buttons (Allow / Always / Deny), with input preview (file path + syntax-highlighted diff), synced with terminal; in forum mode, buttons appear in the project topic
• Auto-Approve Permissions — configure allowed tools in settings.local.json (permissions.allow patterns like "Edit(*)", "Bash(*)") to skip Telegram approval for trusted operations
• Statistics & Logging — /stats for API usage and tokens, /logs for per-session request logs
• Web Dashboard — real-time stats (by provider, project, operation, session), token charts, cost estimation including Anthropic CLI sessions, error drill-down with slide panel, log viewer with full message detail; Projects page for creating, starting, and stopping projects from the browser
• Telegram Mini App — mobile WebApp (Dev Hub button) with git browser (files/log/status/diffs), permission manager (Allow/Deny/Always), and session monitor with API stats (by model, including Anthropic CLI usage); auto-themed to Telegram's light/dark mode

Operations

• Health Endpoint — GET /health with DB status, uptime, active sessions
• Auto-Cleanup — hourly cleanup of old queue messages, logs, stats, and all disconnected sessions; supports CLEANUP_DRY_RUN=true for safe inspection
• CLI Tool — interactive setup wizard, session management, backup, monitoring
• Docker-First — bot + PostgreSQL in Docker Compose, Ollama on host

Architecture Quality

• Service Layer — services/ directory with SessionService, ProjectService, PermissionService, MemoryService, MessageService, SummarizationService; typed wrappers over raw SQL with atomic operations
• Zod Config Validation — all env vars parsed and validated at startup via config.ts; bot exits immediately on missing required vars
• Structured Logging (Pino) — JSON-structured logs throughout the codebase; LOG_LEVEL env var; channelLogger writes to stderr fd 2 for MCP stdio compatibility
• Unit Test Suite — 77 pure unit tests in tests/unit/ covering session lifecycle, permission state machine, memory reconciliation, and forum topic routing; runs in ~30ms with bun test tests/unit/
• Security Defaults — bot exits immediately at startup if ALLOWED_USERS is empty and ALLOW_ALL_USERS=true is not set; no silent open-access deployments
• Session State Machine — sessions/state-machine.ts enforces valid status transitions (active→inactive, active→terminated, inactive→active); invalid transitions are blocked and logged

Architecture

                          ┌──────────────────────────────────────────────────┐
                          │      Host / Laptop / Any terminal                │
                          │                                                  │
  ┌─────────────┐ stdio   │  ┌───────────┐  ┌───────────┐  ┌───────────┐   │
  │ channel/    │◀═══════▶│  │ Claude CLI│  │ Claude CLI│  │ Claude CLI│   │
  │ (7 modules: │  MCP    │  │ project-a │  │ project-b │  │ general   │   │
  │  session,   │         │  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  │
  │  perms,     │         │        │   Bash/Read/Edit/Write       │         │
  │  tools,     │         │        ▼              ▼              ▼          │
  │  poller,    │         │  ┌──────────────────────────────────────────┐   │
  │  status,    │         │  │           Project Files (host)           │   │
  │  telegram)  │         │  └──────────────────────────────────────────┘   │
  └──────┬──────┘         │        │   Bash/Read/Edit/Write       │         │
         │ polls           │        ▼              ▼              ▼          │
         │ message_queue   │  ┌──────────────────────────────────────────┐   │
         │                 │  │           Project Files (host)           │   │
         │                 │  └──────────────────────────────────────────┘   │
         │                 │                                                  │
         │                 └──────────────────────────────────────────────────────┘
         │                            ▲
         │                 ┌──────────┴───────────────────────────────────────┐
         │                 │              Docker                              │
         │  direct DB      │                                                  │
         ├────────────────▶│  ┌──────────────────────────────────────────┐   │
         │                 │  │  Bot (main.ts)                    :3847  │   │
         │                 │  │                                          │   │
         │                 │  │  Telegram polling ◀──▶ Telegram API      │   │
         │                 │  │  HTTP MCP server  ◀──▶ Claude CLIs      │   │
         │                 │  │                                          │   │
         │                 │  │  adapters/                               │   │
         │                 │  │  └─ ClaudeAdapter → message_queue        │   │
         │                 │  │                                          │   │
         │                 │  │  services/  (SessionService,             │   │
         │                 │  │             ProjectService,              │   │
         │                 │  │             PermissionService,           │   │
         │                 │  │             MemoryService)               │   │
         │                 │  │                                          │   │
         │                 │  │  sessions/router.ts (standalone/cli/disc)│   │
         │                 │  │  Stand

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MrCipherSmith](https://github.com/MrCipherSmith)
- **Source:** [MrCipherSmith/helyx](https://github.com/MrCipherSmith/helyx)
- **License:** MIT
- **Homepage:** https://helyx.mrciphersmith.com

Install and usage instructions live in the source repository linked above.