Metadata-Version: 2.4
Name: faltoobot
Version: 5.1.0
Summary: WhatsApp-first LLM bot
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: neonize>=0.3.16.post0
Requires-Dist: openai>=2.32.0
Requires-Dist: playwright>=1.58.0
Requires-Dist: pillow>=12.2.0
Requires-Dist: rich>=14.3.4
Requires-Dist: textual[syntax]>=8.2.3
Requires-Dist: pyobjc-framework-Cocoa>=11.1; sys_platform == "darwin"
Requires-Dist: tree-sitter-lua>=0.5.0
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: google-genai>=1.73.1
Requires-Dist: textual-speedups>=0.2.1
Requires-Dist: certifi>=2026.4.22
Dynamic: license-file

# faltoobot

[![tests](https://img.shields.io/github/actions/workflow/status/pratyushmittal/FaltooBot/main.yml?branch=main&label=tests)](https://github.com/pratyushmittal/FaltooBot/actions/workflows/main.yml)
![coverage](https://img.shields.io/badge/coverage-78%25-brightgreen)

`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 configure` to set up OpenAI and WhatsApp.
- Run `faltoobot whatsapp` to keep the bot running.
- Message that WhatsApp number from your own number.

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

For faster project and code search inside `faltoochat`, install `ripgrep` (`rg`) too:

```bash
# macOS
brew install ripgrep

# Ubuntu / Debian
sudo apt-get update && sudo apt-get install -y ripgrep

# Fedora
sudo dnf install ripgrep

# Arch Linux
sudo pacman -S ripgrep
```

`faltoochat` falls back without `rg`, but search is faster and more reliable when it is installed.

## Quick start

### 1. Configure

```bash
faltoobot configure
```

The configure flow shows a simple menu:
- Wizard
- WhatsApp
- Codex / OpenAI

The wizard is the default. It helps you:
- sign in with Codex / ChatGPT OAuth, or set an OpenAI API key
- choose model / thinking / transcription settings
- pair the WhatsApp account

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

```toml
[openai]
api_key = "your_key_here"
oauth = ""
model = "gpt-5.5"
thinking = "high"
fast = false

[bot]
allow_group_chats = ["120363000000000000@g.us"]
allowed_chats = ["15551234567"]
system_prompt = "You are Faltoobot, a concise and helpful AI assistant replying inside WhatsApp. Keep replies practical and readable on mobile."
```

If `oauth` is set, Faltoobot prefers that OAuth auth file over `api_key`. If `oauth` is blank, Faltoobot falls back to `OPENAI_API_KEY` from the environment.

Set `allowed_chats` to the WhatsApp phone numbers or JIDs that should be allowed to talk to the bot in direct chats. Faltoobot normalizes phone numbers into WhatsApp JIDs when saving the config.
If you enable groups, set `allow_group_chats` to the group JIDs that the bot should keep history for and reply in. If it is empty, the bot will ignore groups. In groups with more than two people, the bot replies only when mentioned or when someone replies to the bot.

### 2. Start WhatsApp service

```bash
faltoobot whatsapp
```

This is the main command for running Faltoobot. It:
- upgrades the installed tool with uv
- ensures config exists
- runs migrations
- stops any old Faltoobot service
- installs the service
- starts the service
- follows logs in the current terminal

Press `Ctrl+C` any time. The service keeps running in the background.

### 3. Watch logs later

```bash
faltoobot logs
```

## Commands

### `faltoobot update`

```bash
faltoobot update
```

Upgrades the installed tool with uv, ensures config exists, and runs migrations.

If uv installs a newer version, Faltoobot asks you to rerun the command so the rest of the flow continues with the newer installed version.

### `faltoobot whatsapp`

```bash
faltoobot whatsapp
```

Best command for normal use. It runs update, refreshes the background service, and follows logs.

### `faltoobot logs`

```bash
faltoobot logs
```

Shows log output in follow mode.

### `faltoobot configure`

```bash
faltoobot configure
```

Opens the setup menu and restarts the service if it is already installed.

## Terminal chat

You can also use Faltoobot locally in the terminal.

### Interactive mode

Run `faltoochat` with no prompt to open the terminal UI:

```bash
faltoochat
faltoochat --workspace=./repo
faltoochat --new-session
```

### One-shot mode

Run `faltoochat` with a prompt to execute a headless one-shot task in that workspace and print the final output to stdout:

```bash
faltoochat "draft a release note"
faltoochat "review unstaged files" --workspace=./repo --new-session
```

### Notify another chat

A one-shot `faltoochat` run can send its final output back to another chat key. This is useful for sub-agents, cron jobs, and detached background tasks:

```bash
faltoochat "List new emails for the user" --workspace=./emails --notify-chat-key=code@main
```

## Commands inside chat

On WhatsApp:

```text
/help
/reset
/status
```

In terminal chat:

```text
/reset
/status
/tree
```

`faltoochat` supports image input, queued prompts while answering, and `Shift+Enter` for multiline input. Paste an image file path or use `Ctrl+V` to attach the current macOS clipboard image. WhatsApp chats now also support incoming image messages, including captioned images, image-only prompts, and multi-image albums.

## Development

Run the Astro docs site locally:

```bash
cd website
npm install
npm run dev
```

Build the static site locally:

```bash
cd website
npm run build
```

## Tests

Run the full test suite with coverage:

```bash
uv run pytest -n auto --cov=faltoobot --cov-report=term-missing:skip-covered
```

Coverage is published in the badge above, and pre-commit enforces a minimum of **78%** line coverage.

Need more details? See `docs/cli.md` and the Astro docs site in `website/`.
