miniclaw

A minimal Telegram agent powered by Claude Code, designed to be self-modifiable.

Why miniclaw?

1. Official Engine: Powered directly by Claude Code. Get Anthropic's state-of-the-art tool-use, codebase awareness, and memory management out of the box, with zero maintenance and automatic updates.
2. Telegram First: The best UI for a personal agent. Enjoy native support for threads, file sharing, voice messages, and real-time work status.
3. Self-Modifying: The codebase is small enough for Claude to understand in one go. Want a new feature? Simply ask the agent to implement it for you.

Features

• Persistent Memory: Context-aware sessions per Telegram chat or thread.
• AI-Managed Tasks: Schedule cron jobs or one-shot reminders simply by telling the agent what you need.
• Rich Media: Full support for images, documents, and voice messages.
• Extensible Skills: Use built-in skills as Telegram slash commands, or ask your agent to build new ones.

Prerequisites

• Go 1.23+
• Claude CLI (installed and authenticated)
• A Telegram bot token from @BotFather
• (Optional) A Groq API key for voice transcription

Setup

AI-Native Installation: use the /setup command within Claude CLI to walk you through prerequisites, configuration, and optionally set up a persistent background service (systemd/launchd).

# 1) First clone miniclaw to your desired location
git clone https://github.com/AaronCQL/miniclaw.git

# 2) Then, change into the miniclaw directory
cd miniclaw

# 3) Launch Claude
claude

# 4) Finally, type: /setup

Once your bot is running, use /commands on Telegram to sync the agent's skills with Telegram and to see all available commands.

Customisation

• agent/preferences.md: your bot's name, personality, timezone, and any preferences you tell it to remember
• agent/CLAUDE.md: the system prompt that defines agent behaviour, sandbox rules, and message formatting

Ask your agent to edit these files to make it your own.

Project structure

The repo has two main concerns: the Go application that wraps Claude CLI, and the agent context that shapes how Claude behaves.

• agent/: the agent's working directory, containing its system prompt (CLAUDE.md) and personality (preferences.md). This is where Claude runs from.
• .claude/skills/: slash command definitions (e.g. /diff, /setup, /restart). Each skill is a directory containing a SKILL.md file that the agent follows as expert instructions.
• cmd/ and internal/: the Go application. Telegram polling, session management, task scheduling, and the Claude CLI runner.

At runtime, all state lives in ~/.miniclaw/: the .env config, session data, scheduled tasks, and a scratch workspace for file operations.