Metadata-Version: 2.4
Name: autobot-cli
Version: 0.1.4
Summary: Agent gateway wrapping Claude Code CLI for Telegram + Cron
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: apscheduler>=3.11.0
Requires-Dist: fastapi>=0.116.0
Requires-Dist: mcp>=1.9.0
Requires-Dist: numpy>=2.1.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: pydantic>=2.11.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-telegram-bot>=21.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.34.0
Requires-Dist: watchfiles>=1.0.0
Provides-Extra: hybrid
Requires-Dist: qdrant-client>=1.12.0; extra == 'hybrid'
Description-Content-Type: text/markdown

# AutoBot

An agent gateway that wraps [Claude Code](https://docs.anthropic.com/en/docs/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

```bash
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](https://t.me/BotFather)
- Your **Telegram chat ID** from [@userinfobot](https://t.me/userinfobot)

## Installation

### From PyPI

```bash
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:
> ```powershell
> $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)

```bash
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/`:

```bash
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

```bash
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

```bash
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

```bash
# 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

```bash
# 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:

```bash
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:

```yaml
# 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](https://modelcontextprotocol.io/) servers:
- **Kanban** -- Task management via [KanbanBoard](https://www.npmjs.com/package/@gzmagyari/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](https://www.npmjs.com/package/@gzmagyari/kanbanboard), a separate task management server. The `autobot init` wizard can set this up, or install manually:

```bash
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`:

```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)

```bash
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
