microclaw/microclaw: An agentic AI assistant that lives in your Telegram chats, inspired by nanoclaw and incorporating some of its design ideas.

English | 中文

Note: This project is under active development. Features may change, and contributions are welcome!

An agentic AI assistant that lives in your Telegram chats, inspired by nanoclaw and incorporating some of its design ideas. MicroClaw connects Claude to Telegram with full tool execution: run shell commands, read/write/edit files, search codebases, browse the web, schedule tasks, and maintain persistent memory across conversations.

Telegram message
    |
    v
 Store in SQLite --> Load chat history + memory
                         |
                         v
                   Claude API (with tools)
                         |
                    stop_reason?
                   /            \
              end_turn        tool_use
                 |               |
                 v               v
           Send reply      Execute tool(s)
                              |
                              v
                        Feed results back
                        to Claude (loop)

Every message triggers an agentic loop: Claude can call tools, inspect the results, call more tools, and reason through multi-step tasks before responding. Up to 25 iterations per request by default.

For a deeper dive into the architecture, design decisions, and what it’s like to use MicroClaw in practice, read the full write-up: Building MicroClaw: An Agentic AI Assistant in Rust That Lives in Your Telegram Chats

• Agentic tool use — bash commands, file read/write/edit, glob search, regex grep, persistent memory
• Session resume — full conversation state (including tool interactions) persisted between messages; Claude remembers tool calls across invocations
• Context compaction — when sessions grow too large, older messages are automatically summarized to stay within context limits
• Sub-agent — delegate self-contained sub-tasks to a parallel agent with restricted tools
• Agent skills — extensible skill system (Anthropic Skills compatible); skills are auto-discovered from data/skills/ and activated on demand
• Plan & execute — todo list tools for breaking down complex tasks, tracking progress step by step
• Web search — search the web via DuckDuckGo and fetch/parse web pages
• Scheduled tasks — cron-based recurring tasks and one-time scheduled tasks, managed through natural language
• Mid-conversation messaging — the agent can send intermediate messages before its final response
• Group chat catch-up — when mentioned in a group, the bot reads all messages since its last reply (not just the last N)
• Continuous typing indicator — typing indicator stays active for the full duration of processing
• Persistent memory — CLAUDE.md files at global and per-chat scopes, loaded into every request
• Message splitting — long responses are automatically split at newline boundaries to fit Telegram’s 4096 char limit

MicroClaw maintains persistent memory via CLAUDE.md files, inspired by Claude Code’s project memory:

data/groups/
    CLAUDE.md                 # Global memory (shared across all chats)
    {chat_id}/
        CLAUDE.md             # Per-chat memory

Memory is loaded into Claude’s system prompt on every request. Claude can read and update memory through tools — tell it to “remember that I prefer Python” and it will persist across sessions.

MicroClaw supports the Anthropic Agent Skills standard. Skills are modular packages that give the bot specialized capabilities for specific tasks.

data/skills/
    pdf/
        SKILL.md              # Required: name, description + instructions
    docx/
        SKILL.md

How it works:

1. Skill metadata (name + description) is always included in the system prompt (~100 tokens per skill)
2. When Claude determines a skill is relevant, it calls activate_skill to load the full instructions
3. Claude follows the skill instructions to complete the task

Built-in skills: pdf, docx, xlsx, pptx, skill-creator

Adding a skill: Create a subdirectory under data/skills/ with a SKILL.md file containing YAML frontmatter (name and description) and markdown instructions.

Commands:

• /skills — list all available skills

For complex, multi-step tasks, the bot can create a plan and track progress:

You: Set up a new Rust project with CI, tests, and documentation
Bot: [creates a todo plan, then executes each step, updating progress]

1. [x] Create project structure
2. [x] Add CI configuration
3. [~] Write unit tests
4. [ ] Add documentation

Todo lists are stored at data/groups/{chat_id}/TODO.json and persist across sessions.

The bot supports scheduled tasks via natural language:

• Recurring: “Remind me to check the logs every 30 minutes” — creates a cron task
• One-time: “Remind me at 5pm to call Alice” — creates a one-shot task

Under the hood, recurring tasks use 6-field cron expressions (sec min hour dom month dow). The scheduler polls every 60 seconds for due tasks, runs the agent loop with the task prompt, and sends results to the originating chat.

Manage tasks with natural language:

"List my scheduled tasks"
"Pause task #3"
"Resume task #3"
"Cancel task #3"

brew tap everettjf/tap
brew install microclaw

git clone https://github.com/microclaw/microclaw.git
cd microclaw
cargo build --release
cp target/release/microclaw /usr/local/bin/

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Enter a display name for your bot (e.g. My MicroClaw)
4. Enter a username (must end in bot, e.g. my_microclaw_bot)
5. BotFather will reply with a token like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz — save this

Recommended BotFather settings (optional but useful):

• /setdescription — set a short description shown in the bot’s profile
• /setcommands — register commands so users see them in the menu:

  reset - Clear current session
  skills - List available agent skills
  

• /setprivacy — set to Disable if you want the bot to see all group messages (not just @mentions)

1. Go to console.anthropic.com
2. Sign up or log in
3. Navigate to API Keys and create a new key
4. Copy the key (starts with sk-ant-)

Edit .env:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234...
ANTHROPIC_API_KEY=sk-ant-...
BOT_USERNAME=my_bot

All configuration is via environment variables (or .env file):

In private chats, the bot responds to every message. In groups, it only responds when mentioned with @bot_username. All messages in groups are still stored for context.

Catch-up behavior: When mentioned in a group, the bot loads all messages since its last reply in that group (instead of just the last N messages). This means it catches up on everything it missed, making group interactions much more contextual.

Web search:

You: Search the web for the latest Rust release notes
Bot: [searches DuckDuckGo, returns top results with links]

Web fetch:

You: Fetch https://example.com and summarize it
Bot: [fetches page, strips HTML, summarizes content]

Scheduling:

You: Every morning at 9am, check the weather in Tokyo and send me a summary
Bot: Task #1 scheduled. Next run: 2025-06-15T09:00:00+00:00

[Next morning at 9am, bot automatically sends weather summary]

Mid-conversation messaging:

You: Analyze all log files in /var/log and give me a security report
Bot: [sends "Scanning log files..." as progress update]
Bot: [sends "Found 3 suspicious entries, analyzing..." as progress update]
Bot: [sends final security report]

Coding help:

You: Find all TODO comments in this project and fix them
Bot: [greps for TODOs, reads files, edits them, reports what was done]

Memory:

You: Remember that the production database is on port 5433
Bot: Saved to chat memory.

[Three days later]
You: What port is the prod database on?
Bot: Port 5433.

src/
    main.rs              # Entry point, CLI
    config.rs            # Environment variable loading
    error.rs             # Error types (thiserror)
    telegram.rs          # Bot handler, agentic tool-use loop, session resume, context compaction, typing indicator
    claude.rs            # Anthropic Messages API client
    db.rs                # SQLite: messages, chats, scheduled_tasks, sessions
    memory.rs            # CLAUDE.md memory system
    skills.rs            # Agent skills system (discovery, activation)
    scheduler.rs         # Background task scheduler (60s polling loop)
    tools/
        mod.rs           # Tool trait + registry (22 tools)
        bash.rs          # Shell execution
        read_file.rs     # File reading
        write_file.rs    # File writing
        edit_file.rs     # Find/replace editing
        glob.rs          # File pattern matching
        grep.rs          # Regex content search
        memory.rs        # Memory read/write tools
        web_search.rs    # DuckDuckGo web search
        web_fetch.rs     # URL fetching with HTML stripping
        send_message.rs  # Mid-conversation Telegram messaging
        schedule.rs      # 5 scheduling tools (create/list/pause/resume/cancel)
        sub_agent.rs     # Sub-agent with restricted tool registry
        activate_skill.rs # Skill activation tool
        todo.rs          # Plan & execute todo tools

Key design decisions:

• Session resume persists full message history (including tool blocks) in SQLite; context compaction summarizes old messages to stay within limits
• Direct API calls to Anthropic (no SDK wrapper) for full control over the tool-use protocol
• SQLite with WAL mode for concurrent read/write from async context
• Exponential backoff on 429 rate limits (3 retries)
• Message splitting for responses exceeding Telegram’s 4096 character limit
• Arc shared across tools and scheduler for thread-safe DB access
• Continuous typing indicator via a spawned task that sends typing action every 4 seconds

MIT