{"id":50843146,"url":"https://github.com/cohe4ko/BotVa","last_synced_at":"2026-07-01T18:01:07.833Z","repository":{"id":348219009,"uuid":"1180310351","full_name":"cohe4ko/BotVa","owner":"cohe4ko","description":"Multi-bot Telegram platform powered by Claude AI with persistent memory, MCP integrations, and team coordination","archived":false,"fork":false,"pushed_at":"2026-06-27T11:30:32.000Z","size":19465,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T13:13:10.991Z","etag":null,"topics":["ai-agent","ai-assistant","anthropic","chatbot","claude-ai","mcp","model-context-protocol","multi-bot","nodejs","self-hosted","telegram","telegram-bot","typescript"],"latest_commit_sha":null,"homepage":"https://botva-installer.onrender.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cohe4ko.png","metadata":{"files":{"readme":"README.en.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T23:08:16.000Z","updated_at":"2026-06-27T11:30:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cohe4ko/BotVa","commit_stats":null,"previous_names":["cohe4ko/botva"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/cohe4ko/BotVa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohe4ko%2FBotVa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohe4ko%2FBotVa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohe4ko%2FBotVa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohe4ko%2FBotVa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cohe4ko","download_url":"https://codeload.github.com/cohe4ko/BotVa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cohe4ko%2FBotVa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35017091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-assistant","anthropic","chatbot","claude-ai","mcp","model-context-protocol","multi-bot","nodejs","self-hosted","telegram","telegram-bot","typescript"],"created_at":"2026-06-14T08:00:22.751Z","updated_at":"2026-07-01T18:01:07.823Z","avatar_url":"https://github.com/cohe4ko.png","language":"TypeScript","funding_links":[],"categories":["Bots"],"sub_categories":[],"readme":"# BotVa\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org)\n\n[🇺🇦 Українська](README.md)\n\nMulti-bot Telegram platform powered by Claude AI. One server — many bots, each with its own role, memory, knowledge, and integrations.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/admin-dashboard.jpg\" alt=\"BotVa Dashboard\" width=\"700\"\u003e\n\u003c/p\u003e\n\n## What Makes BotVa Different\n\n- **Memory as a first-class entity.** Facts in SQLite (topic, tags, access_count) + daily diary logs + weekly consolidations via Claude. Consolidation runs automatically every night\n- **Bot team.** Bots communicate via Unix sockets (Colleague MCP), a manager distributes tasks in parallel via `Promise.allSettled()`\n- **Full isolation.** Each bot is a separate process with its own .env, database, knowledge, memory, voice, and role. All managed from one admin panel\n- **Live management.** Web panel for creating bots, image gallery, cron tasks, backups, diagnostics. Model and temperature change without restart; .env changes require restart via UI\n- **Dynamic integrations.** MCP servers connect based on env variables — add `BITRIX24_WEBHOOK_URL`, restart the bot and it gets CRM. No code changes\n- **Philosophy.** The base role (`_soul.md`) is a manifesto: how to think, how to communicate, when to stay silent. Not \"certainly!\", but a human conversation\n\n## Key Features\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/telegram-demo-result.jpg\" alt=\"Bot in action — parallel tools\" width=\"500\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eParallel execution: web search, image generation, Python chart, currency rates — in a single request\u003c/em\u003e\u003c/p\u003e\n\n- **Multiple bots** from a single Node.js instance\n- **12 ready-made roles** — from personal assistant to webmaster\n- **Memory** — facts (long-term storage) + daily diary logs with consolidation\n- **Voice** — voice messages and responses (Groq STT + Edge TTS)\n- **Images** — generation and editing via Gemini with auto-gallery\n- **Gemini AI** — second opinion (AskGemini) and search with citations (GeminiSearch)\n- **Bot team** — communication via Unix sockets, task delegation\n- **Scheduler** — cron tasks with full tool access\n- **Utilities** — currency rates, time, Python sandbox, email, Telegraph\n- **Integrations** — Google Workspace, smart home, any MCP servers\n- **Web search** — search, scraping, AI browser (Stagehand)\n- **Admin panel** — full web interface for management\n- **Backups** — full and per-bot, with SHA256 verification\n\n## Quick Start\n\n### Install on VPS (fastest way)\n\nOpen **https://botva-installer.onrender.com/**, enter your server IP and Telegram token -- and in 3-5 minutes the bot is running. Details: [DEPLOY.md](DEPLOY.md)\n\n### Local Installation\n\n```bash\n# 1. Clone\ngit clone https://github.com/cohe4ko/BotVa.git BotVa\ncd BotVa\n\n# 2. Install dependencies and build\n./scripts/deploy.sh setup\n\n# 3. Create your first bot (option A: CLI)\nnpm run new-bot -- my-bot personal-assistant --emoji 🧑‍💼 --name \"My Bot\"\n\n# 3. Create your first bot (option B: web interface)\n./scripts/deploy.sh admin  # Start admin panel\n#    Open http://localhost:3000 → Create Bot\n#    Token and chat ID are entered in the creation form\n\n# 4. Configure tokens (if using CLI)\n#    Edit bots/my-bot/.env:\n#    - TELEGRAM_BOT_TOKEN  (get from @BotFather in Telegram)\n#    - ALLOWED_CHAT_ID     (send /chatid to the bot after starting)\n\n# 5. Start\n./scripts/deploy.sh start\n```\n\nAfter starting, message your bot in Telegram — it will respond.\n\n\u003cdetails\u003e\n\u003csummary\u003eCreating a bot via web interface\u003c/summary\u003e\n\n\u003cimg src=\"screenshots/admin-create-bot.jpg\" alt=\"Create Bot\" width=\"700\"\u003e\n\nChoose a role, enter the Telegram token from @BotFather and your chat ID. API keys can be added later.\n\n\u003cimg src=\"screenshots/admin-bot-created.jpg\" alt=\"Bot created\" width=\"700\"\u003e\n\nAfter creation — file structure and next steps.\n\u003c/details\u003e\n\n## Bot Roles\n\nWhen creating a bot you choose a role — it defines specialization, tools, and style.\n\n| Role | Slug | Description |\n|------|------|-------------|\n| Personal Assistant | `personal-assistant` | Daily tasks, calendar, CRM, smart home |\n| Researcher | `researcher` | Deep analysis, fact verification, reports |\n| Health | `health-advisor` | Health metrics monitoring, lab results, recommendations |\n| Academic | `academic` | Scientific papers, methodology, PhD, teaching |\n| Creative | `creative` | Design, images, presentations, copywriting |\n| Sales | `sales` | Leads, deals, sales analysis, proposals |\n| Planner | `planner` | Tasks, deadlines, prioritization |\n| Knowledge Base | `knowledge-base` | Documentation, FAQ, knowledge search |\n| Manager | `manager` | Bot team coordination, task delegation |\n| Product/Market | `product-market` | CRM analytics, positioning, competitors |\n| Webmaster | `webmaster` | Website, content, deploy, SEO |\n| Debate Researcher | `debate-researcher` | Analysis from opposing perspectives |\n\n```bash\nnpm run new-bot -- \u003cslug\u003e \u003crole\u003e [--emoji 🤖] [--name \"Name\"]\n```\n\n## Features\n\n### Telegram\n\nFirst interaction with the bot — greeting, profile setup, reminders, and search with clarifying questions:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/telegram-start.jpg\" alt=\"First interaction\" width=\"400\"\u003e\n  \u003cimg src=\"screenshots/telegram-askuser.jpg\" alt=\"AskUser — clarifying questions\" width=\"400\"\u003e\n\u003c/p\u003e\n\n### Voice\n\nThe bot understands voice messages and can respond with voice. STT via Groq Whisper (requires `GROQ_API_KEY`), TTS via Edge-TTS (free). The `/voice` command toggles voice responses.\n\n### Images\n\nGeneration and editing via Gemini (`GOOGLE_API_KEY`). Use `/img description` or just ask in chat. All images are saved to the gallery.\n\n### Memory\n\nThree-tier system: facts (persistent storage with topics and tags), daily markdown logs, workspace files (USER.md, MEMORY.md). Consolidation at `NIGHT_OWL_HOUR`.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/telegram-memory.jpg\" alt=\"Saving facts to memory\" width=\"400\"\u003e\n  \u003cimg src=\"screenshots/telegram-user-profile.jpg\" alt=\"User profile via AskUser\" width=\"400\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eLeft: saving facts via SaveFact/SearchMemory. Right: profile setup via AskUser\u003c/em\u003e\u003c/p\u003e\n\n### Scheduler\n\nCron tasks: `/schedule 0 9 * * * What's on my agenda today?`. Standard 5-field cron.\n\n### Bot Team\n\nA manager coordinates work, bots communicate via Colleague MCP (Unix sockets). Each bot can reach the manager via `ask_manager()`.\n\n### Telegram\n\nSendMedia (photos, documents, albums), ForwardMessage, SetReaction, PinMessage, OpenWebApp (Mini App), AskUser (buttons, polls).\n\n### Utilities\n\nCurrencyRates (cash exchange rates), GetCurrentTime, RunPython (sandbox), SendEmail (SMTP), PublishTelegraph.\n\n### Workspace Files\n\nThe bot reads and updates its files between sessions: USER.md (profile), MEMORY.md (memory) via ReadWorkspaceFile / WriteWorkspaceFile.\n\nDetailed guide: [MANUAL.md](MANUAL.md)\n\n## Integrations\n\n| Integration | MCP Server | Required Variables |\n|-------------|-----------|-------------------|\n| Google Calendar, Gmail, Drive | `google-workspace` | `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET` |\n| Home Assistant | `home-assistant` | `HA_URL`, `HA_TOKEN` |\n\n## Admin Panel\n\n\u003cimg src=\"screenshots/admin-dashboard-5bots.jpg\" alt=\"Dashboard — 5 bots\" width=\"700\"\u003e\n\nWeb interface for bot management. Two ways to start:\n\n```bash\n# 1. From Telegram (on-demand, auto-stops after 20 min)\n/admin\n\n# 2. As a standalone service (persistent)\n./scripts/deploy.sh admin\n```\n\n| Section | Description |\n|---------|-------------|\n| Dashboard | Bot status, requests, costs, services |\n| Config | Model, temperature, env variables, workspace files |\n| Knowledge | Bot knowledge files |\n| Facts | Memory: view, search, edit |\n| Tasks | Scheduled cron tasks |\n| Settings | Chat settings, sessions |\n| Usage | Token analytics and costs |\n| System | Builtin tools, MCP servers, skills on/off |\n| Images | Generated image gallery |\n| Logs | Event audit log |\n| Diagnostics | AI-powered system diagnostics |\n| Backup | Create and restore backups |\n| Team | Bot team management |\n| Templates | Role templates |\n| Terminal | Browser shell |\n| Create Bot | New bot creation wizard |\n\nDetailed guide: [MANUAL.md](MANUAL.md)\n\n## Telegram Commands\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/telegram-commands.jpg\" alt=\"Telegram commands\" width=\"400\"\u003e\n  \u003cimg src=\"screenshots/telegram-settings.jpg\" alt=\"Bot settings\" width=\"400\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eCommands /usage, /model, /facts, /settings — manage the bot from Telegram\u003c/em\u003e\u003c/p\u003e\n\n| Command | Description |\n|---------|-------------|\n| `/start` | Greeting and chat ID |\n| `/chatid` | Show chat ID |\n| `/newchat`, `/forget` | Clear session (memory persists) |\n| `/voice` | Toggle voice responses |\n| `/img \u003cdescription\u003e` | Generate an image |\n| `/model` | Switch model (Opus/Sonnet/Haiku) |\n| `/schedule \u003ccron\u003e \u003ctext\u003e` | Create a scheduled task |\n| `/usage` | Token statistics |\n| `/stats` | Inline stats on/off |\n| `/lang` | Interface language |\n| `/admin` | Admin panel |\n| `/session` | Browse CLI sessions |\n| `/cancel` | Cancel current request |\n\n## Project Structure\n\n```\nBotVa/\n├── src/                    # Platform code (TypeScript)\n│   ├── index.ts            # Entry point\n│   ├── bot.ts              # Telegram bot\n│   ├── agent.ts            # Claude agent with MCP\n│   ├── builtin-tools.ts    # Built-in tools\n│   ├── memory.ts           # Memory system\n│   ├── db.ts               # SQLite\n│   ├── voice.ts            # STT/TTS\n│   ├── imagen.ts           # Image generation\n│   ├── scheduler.ts        # Scheduler\n│   └── admin/              # Web admin panel\n├── roles/                  # Role templates\n│   ├── _soul.md            # Base character (for all bots)\n│   ├── _tools.md           # Base tool routing\n│   └── *.md                # Roles (personal-assistant, researcher, ...)\n├── mcp-servers/            # MCP servers\n│   ├── colleague/          # Inter-bot communication\n│   └── manager/            # Manager coordination\n├── scripts/                # Management scripts\n├── installer/              # Web installer\n├── bots/                   # Bot data (gitignored)\n├── workspace/              # Runtime data (gitignored)\n├── .env.example            # Configuration template\n└── package.json\n```\n\n## Management\n\n```bash\n./scripts/deploy.sh setup      # Install dependencies, build\n./scripts/deploy.sh start      # Start all bots\n./scripts/deploy.sh stop       # Stop\n./scripts/deploy.sh restart    # Restart\n./scripts/deploy.sh build      # Rebuild TypeScript + MCP\n./scripts/deploy.sh status     # Status\n./scripts/deploy.sh backup     # Backup\n./scripts/deploy.sh restore    # Restore\n```\n\n## Deploy\n\nDetailed guide with configuration and all options: [DEPLOY.md](DEPLOY.md)\n\n## Tech Stack\n\n- **Runtime**: Node.js 20+, TypeScript (strict)\n- **Telegram**: Grammy\n- **AI**: Anthropic Claude Agent SDK\n- **Database**: SQLite (built into Node.js)\n- **Web**: Hono\n- **Voice**: Edge-TTS (synthesis), Groq Whisper (recognition)\n- **Images**: Google Gemini\n- **Browser**: Stagehand / Playwright\n- **Tests**: Vitest 4.x\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## FAQ\n\n**How do I find my chat ID?**\nStart the bot and send `/start` or `/chatid`.\n\n**How do I add knowledge to a bot?**\nPlace .md or .txt files in `bots/\u003cname\u003e/knowledge/`. Also available via admin panel (Knowledge).\n\n**How do I connect an integration?**\nAdd the required variables to the bot's `.env`. After restart, the bot automatically gets the tools.\n\n**How do I migrate to another server?**\nSee the \"Migration\" section in [DEPLOY.md](DEPLOY.md).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcohe4ko%2FBotVa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcohe4ko%2FBotVa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcohe4ko%2FBotVa/lists"}