# 📱 CallMe

**CallMe** is an AI-powered background agent that lets you control your computer via Telegram using plain natural language.

---

## Features

- **Natural language commands** → the AI maps your words to the right tool automatically
- **40+ built-in tools** — system health, screenshots, weather, shell, file management, reminders, volume, clipboard, and more
- **9 AI providers** supported out of the box (OpenAI, Anthropic, Groq, Together, NVIDIA, Mistral, Cohere, Zhipu, OpenRouter) — several offer **free tiers**
- **Encrypted config** — your API keys and Telegram token are stored with Fernet symmetric encryption
- **Dangerous-action confirmation** — shell commands and deletes require a tap of ✅ before executing
- **No external dependencies beyond stdlib + 3 packages** (`click`, `psutil`, `cryptography`)
- **Cross-platform** — macOS, Linux, Windows

---

## Quick Start

```bash
pip install callme

callme init    # one-time interactive setup (~2 minutes)
callme run     # start the agent in the foreground
```

### Background daemon
```bash
nohup callme run &
```

### Stop / check
```bash
callme stop
callme status
callme doctor   # full diagnostic
```

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `callme init` | Interactive setup wizard |
| `callme init --reconfigure` | Re-run setup (overwrites existing config) |
| `callme run` | Start the agent (foreground) |
| `callme run --background` | Start as a background daemon |
| `callme stop` | Gracefully stop the agent |
| `callme status` | Show running status and config summary |
| `callme doctor` | Full diagnostic (deps, connectivity, config) |

---

## Telegram Commands

| Command | Description |
|---------|-------------|
| `/start` | Welcome message & examples |
| `/help` | List all commands |
| `/health` | CPU / RAM / disk overview |
| `/screenshot` | Capture and send screen |
| `/weather <city>` | Current weather |
| `/ls [path]` | List directory contents |
| `/run <cmd>` | Run a shell command (with confirmation) |
| `/ps` | Top processes |
| `/battery` | Battery status |
| `/ping [host]` | Network latency |
| `/memory` | RAM usage |
| `/disk [path]` | Disk usage |
| `/time` | Current date/time |
| `/clear` | Clear AI conversation memory |

Or just type anything in natural language!

---

## Natural Language Examples

```
how's my cpu?
take a screenshot
what's the weather in Paris?
remind me in 30 minutes to call mom
list files in ~/Downloads
show me the contents of /etc/hosts
run df -h
what's my IP?
calculate 12 * (3 + 7)^2
kill process firefox
open https://news.ycombinator.com
check if google.com is reachable
```

---

## Available Tools

| Tool | Description |
|------|-------------|
| `system_health` | CPU, RAM, disk, swap, top processes |
| `uptime` | System uptime and boot time |
| `battery` | Battery level and charging status |
| `network_stats` | Network I/O and active connections |
| `list_processes` | All running processes |
| `kill_process` ⚠️ | Terminate by PID or name |
| `run_shell` ⚠️ | Execute any shell command |
| `list_directory` | Directory listing |
| `read_file` | Read a text file |
| `write_file` ⚠️ | Write/append to a file |
| `delete_file` ⚠️ | Delete a file or directory |
| `copy_file` | Copy file or directory |
| `move_file` ⚠️ | Move or rename |
| `search_files` | Find files by name pattern |
| `create_directory` | Create directory tree |
| `disk_usage` | Disk space for a path |
| `screenshot` | Full-screen capture |
| `get_volume` | Current volume level |
| `set_volume` | Set volume 0–100 |
| `mute_volume` | Mute audio |
| `get_clipboard` | Read clipboard |
| `set_clipboard` | Write to clipboard |
| `weather` | Current weather (open-meteo, free) |
| `ping` | Ping a host |
| `internet_speed` | Connectivity check |
| `open_url` | Open URL in browser |
| `open_application` | Launch an app |
| `datetime` | Current date/time/timezone |
| `reminder` | Timed Telegram reminder |
| `python_info` | Python version and packages |
| `env_vars` | Environment variables |
| `git_status` | Git repo status |
| `git_log` | Recent commits |
| `pip_install` ⚠️ | Install Python package |
| `pip_list` | List installed packages |
| `calculate` | Safe math evaluation |
| `word_count` | Word/char/line count |

⚠️ = requires confirmation tap before execution

---

## Configuration

Config is stored in:
- **Linux:** `~/.local/share/callme/data/`
- **macOS:** `~/Library/Application Support/callme/data/`
- **Windows:** `%APPDATA%\callme\data\`

The API key and Telegram token are encrypted at rest using a Fernet key stored at `data/.enc_key` (permissions: 600).

---

## Requirements

- Python 3.10+
- `click`, `psutil`, `cryptography` (auto-installed by `callme init`)
- A Telegram bot token (free, from @BotFather)
- An API key for your chosen AI provider

---

## License

MIT
