Metadata-Version: 2.4
Name: faltoobot
Version: 0.1.1
Summary: WhatsApp-first LLM bot
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: neonize>=0.3.15.post0
Requires-Dist: openai>=2.28.0
Requires-Dist: pillow>=11.3.0
Requires-Dist: rich>=14.2.0
Requires-Dist: textual>=8.1.1

# faltoobot

`faltoobot` is a personal assistant that lives on its own WhatsApp account.

## How it works

- Get a separate SIM / WhatsApp account for Faltoobot.
- Sign in to that account on a spare phone.
- Install `faltoobot` on a computer that will stay online.
- Run `faltoobot auth` and scan the QR code from that phone.
- Message that WhatsApp number from your own number.

## Usage

### Install

```bash
uv tool install faltoobot
```

Then you can run `faltoobot` and `faltoochat` from any folder.

If uv asks you to add its tool bin directory to your `PATH`, run:

```bash
uv tool update-shell
```

### Configure

```bash
faltoobot configure
```

Example `~/.faltoobot/config.toml`:

```toml
[openai]
api_key = "your_key_here"
model = "gpt-5.2"
thinking = "none"
fast = false

[bot]
allow_groups = false
allowed_chats = ["15551234567@s.whatsapp.net"]
system_prompt = "You are Faltoobot, a concise and helpful AI assistant replying inside WhatsApp. Keep replies practical and readable on mobile."
```

If `api_key` is left blank, Faltoobot falls back to `OPENAI_API_KEY` from the environment.

Set `allowed_chats` to your own WhatsApp JID or phone number to keep the bot private. Leave it empty only if you want Faltoobot to reply to anyone who can message that account.

### Pair and run

Pair the WhatsApp account once:

```bash
faltoobot auth
```

Then start the bot:

```bash
faltoobot run
```

### Terminal chat

You can also use Faltoobot locally in the terminal:

```bash
faltoobot chat
faltoobot chat --name "Scratchpad"
faltoochat
```

### Commands

On WhatsApp:

```text
/help
/reset
```

In terminal chat:

```text
/help
/reset
/exit
```

`faltoochat` also supports image input. Paste an image file path, paste markdown like `![alt](path)`, or use `Ctrl+V` to attach the current macOS clipboard image.

### Update

```bash
uv tool upgrade faltoobot
```

Need more details? See `docs/guide.md`.
