⚡ ArmanBot — Personal AI Agent in Telegram

Your AI agent that actually does things — not just talks.

One file. No dependencies. Just Node.js + Claude Code CLI.

What it does

• 🛠 Executes commands — bash, git, ssh, files on your machine
• 🧠 Remembers — persistent memory between sessions
• 🎭 Has personality — customizable via SOUL.md
• 🔍 Searches the web — real-time information
• 📁 Manages files — read, write, edit, search
• 🔊 Speaks — voice messages via ElevenLabs (optional)
• 🏠 Controls smart home — MQTT (optional)
• 📧 Handles email — via himalaya CLI (optional)

Quick Start

One command install (macOS/Linux):

curl -fsSL https://armanbot.kz/install.sh | bash

Manual install:

1. Prerequisites:

   • Node.js 22+
   • Claude Code CLI with active subscription
   • Telegram bot token from @BotFather

2. Clone and run:

   git clone https://github.com/armanbot-jpg/armanbot-telegram.git
   cd armanbot-telegram
   ARMANBOT_TOKEN="your-telegram-token" node bot.mjs

3. Message your bot in Telegram. That's it.

Configuration

All config via environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | ARMANBOT_TOKEN | ✅ | — | Telegram bot token from @BotFather | | ARMANBOT_MODEL | — | opus | Claude model: opus, sonnet, haiku | | ARMANBOT_TIMEOUT | — | 180000 | Request timeout in ms | | ARMANBOT_WORKSPACE | — | ~/.armanbot/workspace | Identity & memory storage | | ARMANBOT_USERS | — | allow all | Comma-separated Telegram chat IDs | | CLAUDE_BIN | — | auto-detect | Path to claude binary |

Identity System

Your agent's personality lives in the workspace:

~/.armanbot/workspace/
├── SOUL.md          # Who your agent is (personality, rules)
├── IDENTITY.md      # Quick reference card
├── AGENTS.md        # Operational rules
├── USER.md          # Info about you (auto-populated)
├── context.md       # Current state (auto-updated)
├── decisions.md     # Decision log (auto-updated)
├── memory/          # Daily notes
├── skills/          # Custom skills (SKILL.md files)
└── logs/            # Session logs

Edit SOUL.md to customize your agent's personality. The bot creates defaults on first run.

Commands

| Command | Description | |---|---| | /start | Welcome message | | /new | Start fresh session | | /status | Current session info |

Run as service

macOS (launchd):

cat > ~/Library/LaunchAgents/ai.armanbot.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key><string>ai.armanbot</string>
    <key>ProgramArguments</key>
    <array><string>$(which node)</string><string>$(pwd)/bot.mjs</string></array>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><true/>
    <key>EnvironmentVariables</key>
    <dict>
        <key>HOME</key><string>$HOME</string>
        <key>PATH</key><string>$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
        <key>ARMANBOT_TOKEN</key><string>YOUR_TOKEN</string>
    </dict>
</dict>
</plist>
EOF
launchctl load ~/Library/LaunchAgents/ai.armanbot.plist

Linux (systemd):

sudo tee /etc/systemd/system/armanbot.service << EOF
[Unit]
Description=ArmanBot AI Agent
After=network.target
[Service]
ExecStart=$(which node) $(pwd)/bot.mjs
Restart=always
User=$USER
Environment=HOME=$HOME
Environment=PATH=$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin
Environment=ARMANBOT_TOKEN=YOUR_TOKEN
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable --now armanbot

Architecture

Telegram → bot.mjs → claude CLI (with tools) → response → Telegram
                ↕
        ~/.armanbot/workspace/
        (SOUL.md, memory, logs)

No API keys needed for Claude — uses your Claude Code CLI subscription (Max/Pro).

License

MIT

Made in Kazakhstan 🇰🇿

armanbot.kz