AutoBot

An agent gateway that wraps Claude Code CLI to provide a Telegram bot interface with sessionful conversations, scheduled cron jobs, a web dashboard, and persistent memory.

Telegram message --> autobot gateway --> claude -p --resume <session> --> JSON response --> Telegram reply
                                                                           └--> actions (schedule job, write memory, ...)

Cron trigger --> autobot gateway --> claude -p --no-session-persistence --> JSON response --> optional Telegram post

• Telegram chats are sessionful -- each chat gets its own Claude Code session, restored on every message via --resume.
• Cron jobs are stateless -- scheduled runs use --no-session-persistence.
• Memory is file-based -- lives in memory/, injected into each run by the gateway.
• Claude outputs structured JSON -- the gateway parses it and executes any requested actions.

Quick Start

pip install autobot-cli
autobot init
autobot run

Prerequisites

• Python 3.11+
• Node.js 18+ (for MCP servers)
• Claude Code CLI (npm install -g @anthropic-ai/claude-code) -- installed and authenticated
• A Telegram bot token from @BotFather
• Your Telegram chat ID from @userinfobot

Installation

From PyPI

pip install autobot-cli

This installs the autobot CLI command and all required dependencies.

Windows note: If autobot isn't recognized after install, add Python's Scripts directory to your PATH:

$scriptsDir = "C:\Users\<YOU>\AppData\Local\Python\...\Scripts"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$scriptsDir", "User")

Restart your terminal afterward. Alternatively, use python -m clawde_app instead of autobot.

From source (development)

git clone https://github.com/gzmagyari/AutoBot.git
cd AutoBot
python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows:     .venv\Scripts\activate
pip install -e .

In development mode, autobot uses the repository root as the data directory. Everything works the same -- no autobot init needed.

With Docker

Docker and compose files live in docker/:

cd docker
cp .env.example .env   # edit with your tokens
docker compose --env-file ./.env up -d --build

Default host ports: Dashboard 18420, Manager API 18421, Qdrant 18433.

Setup

Interactive wizard

autobot init

This will:

1. Ask for your Telegram bot token and chat ID
2. Create ~/.autobot/ with config, rules, hooks, skills, and MCP templates
3. Optionally set up the Kanban Dashboard (task management)

Verify the environment

autobot doctor

autobot doctor
==============
- Python: 3.13.2
- Config: OK (config.yaml)
- Data home: /home/you/.autobot
- DB path: /home/you/.autobot/clawde.db
- Claude CLI: OK (2.1.37 (Claude Code))
- npx: OK
- Kanban Dashboard: OK (http://kanbanboard.local:3000)
- Agent 'clawde' token: OK

Usage

Running the gateway

# Foreground (see logs in terminal)
autobot run

# Background (writes PID file)
autobot start

# Stop / restart
autobot stop
autobot restart

# Check if running
autobot status

Once running, send a message to your Telegram bot. It responds using Claude Code with full tool access.

CLI Reference

autobot [--config PATH] [--data-dir PATH] [--log-level LEVEL] <command>

Command	Description
run	Run the gateway in the foreground
start	Start as a background process
stop	Stop the running gateway
restart	Stop + start
status	Check if the gateway is running
manager	Run the process manager API
doctor	Run environment checks
init	Interactive setup wizard

Option	Description
--config PATH	Path to config YAML (auto-detected if omitted)
--data-dir PATH	Data directory (overrides AUTOBOT_DATA_DIR env var)
--log-level LEVEL	DEBUG, INFO, WARNING, or ERROR (default INFO)
--version	Print version and exit

Data Directory

By default, AutoBot stores all user data in ~/.autobot/:

~/.autobot/
  .autobot-root              # Sentinel marker
  config.yaml                # Main config (bot tokens, settings)
  .env                       # Optional environment variables
  clawde.db                  # SQLite database
  agents/                    # Per-agent soul, memory, skills
  skills/                    # User's custom global skills
  mcp/servers/               # MCP server definitions
  memory/                    # Global memory
  runtime/                   # Logs, context, PID files
  .claude/                   # Claude Code rules, hooks, settings
  CLAUDE.md                  # Claude Code project instructions

Custom data directory

# Via flag
autobot --data-dir ~/.autobot-work run

# Via environment variable
export AUTOBOT_DATA_DIR=~/.autobot-work
autobot run

Multiple instances

Each --data-dir is a fully independent instance with its own config, database, agents, and ports:

autobot run                            # uses ~/.autobot/
autobot --data-dir ~/.autobot-work run # separate instance

Configure different web.port values in each instance's config.yaml to avoid port conflicts.

Configuration

Edit config.yaml in your data directory:

# Agent definitions (one per Telegram bot)
agents:
  clawde:
    bot_token: "YOUR_BOT_TOKEN"
    allowed_chat_ids: [YOUR_CHAT_ID]
    admin_chat_ids: [YOUR_CHAT_ID]

# Claude Code settings
claude:
  executable: "claude"
  model: null
  output_format: "stream-json"
  tool_profiles:
    safe_chat:
      tools: ""
      allowed_tools: ""
    read_only:
      tools: "Read,Grep,Glob"
      allowed_tools: "Read,Grep,Glob"
    dev:
      tools: "Read,Edit,Bash,Grep,Glob"
      allowed_tools: "Read,Edit,Grep,Glob"

# Memory
memory:
  daily_include_days: 2
  retrieval:
    strategy: "keyword"   # or "hybrid" with qdrant
    max_snippets: 6

# Web dashboard
web:
  enabled: true
  host: "0.0.0.0"
  port: 8420

# Scheduler
scheduler:
  timezone: "Europe/London"
  max_concurrent_jobs: 2

Telegram Commands

Command	Description
/help	Show available commands
/status	Show current chat status (session, tool profile)
/pair <code>	Pair this chat (if allowlist is enforced)
/mode <profile>	Switch tool profile (safe_chat, read_only, dev)
/jobs	List scheduled cron jobs
/job <id>	Show details for a specific job
/memory	Show recent memory entries

Any regular text message is forwarded to Claude via the gateway.

Tool Profiles

Profile	Tools	Use case
safe_chat	None	Pure conversation, no file/shell
read_only	Read, Grep, Glob	Can read codebase but not modify
dev	Read, Edit, Bash, Grep, Glob	Full development access (admin only)

Switch profiles per-chat with /mode <profile>.

Features

Memory

• Persistent file-based memory (memory/)
• Per-agent memory isolation
• Daily logs and topic-based organization
• Keyword retrieval injected into each Claude run
• Optional hybrid search with Qdrant vector database (pip install autobot-cli[hybrid])

MCP Servers

Bundled Model Context Protocol servers:

• Kanban -- Task management via KanbanBoard
• Memory -- Memory search and retrieval
• Chrome DevTools -- Browser automation
• Qdrant -- Vector search (optional, requires Docker)

Skills

Built-in skills that extend the agent:

• Goal Achiever -- Long-horizon goal pursuit with structured planning
• Email Sender -- Send and read emails via Gmail
• Kanban Autonomous -- Autonomous task management

Web Dashboard

A Vue.js dashboard (default: http://localhost:8420) for monitoring agents, viewing logs, and system management.

Cron Jobs

Claude can request cron jobs via structured actions. Jobs are stored in SQLite and managed by APScheduler.

• cron -- standard cron expression (e.g., 0 9 * * *)
• interval -- repeat every N seconds/minutes/hours
• once -- fire once at a specific datetime

Kanban Dashboard

AutoBot integrates with KanbanBoard, a separate task management server. The autobot init wizard can set this up, or install manually:

npm install -g @gzmagyari/kanbanboard
kanbanboard init
kanbanboard start

The kanban server can run on any machine on your local network. Configure the URL in mcp/servers/kanban.json:

{
  "env": {
    "KANBAN_BASE_URL": "http://kanbanboard.local:3000"
  }
}

Point kanbanboard.local to the right IP in your hosts file, or use a direct IP/hostname.

Security

• Secrets are protected: data/, .env, key files are blocked by .claude/settings.json deny rules and PreToolUse hooks.
• Dangerous commands are blocked: destructive shell commands are denied by a Bash hook.
• Pairing system: optionally require chats to pair with a one-time code.
• Tool profiles: limit what Claude can do per-chat.

Publishing (maintainers)

pip install build twine

# 1. Bump version in clawde_app/__init__.py

# 2. Build
rm -rf dist/                           # Linux/Mac
# Remove-Item -Recurse -Force dist     # Windows
python -m build --wheel

# 3. Upload
twine upload dist/*
# Username: __token__
# Password: pypi-...  (from https://pypi.org/manage/account/token/)

PyPI does not allow re-uploading the same version. Always bump before publishing.

License

MIT