# Helyx > Helyx — Telegram-first multi-project hub for Claude Code. Multi-session MCP bot with dual-layer memory, voice transcription, web dashboard, and real-time CLI monitoring. - **Type:** MCP server - **Install:** `agentstack add mcp-mrciphersmith-helyx` - **Verified:** Pending review - **Seller:** [MrCipherSmith](https://agentstack.voostack.com/s/mrciphersmith) - **Installs:** 0 - **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [MrCipherSmith](https://github.com/MrCipherSmith) - **Source:** https://github.com/MrCipherSmith/helyx - **Website:** https://helyx.mrciphersmith.com ## Install ```sh agentstack add mcp-mrciphersmith-helyx ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](CLAUDE_MD_GUIDE.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 ```bash 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: ```bash 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](https://modelcontextprotocol.io) 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 $DEEPSEEK_API_KEY` `` 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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-mrciphersmith-helyx - Seller: https://agentstack.voostack.com/s/mrciphersmith - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.