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
faltooboton a computer that will stay online. - Run
faltoobot updateonce after install to create~/.faltoobot/config.toml. - Edit
~/.faltoobot/config.tomlif you need to change defaults. - Run
faltoobot codex-loginto sign in with Codex / ChatGPT OAuth, or setopenai.api_keyin config. - Run
faltoobot whatsappto keep the bot running. - Message that WhatsApp number from your own number.
Install
uv tool install faltoobot
Then run the setup/update step once:
faltoobot update
This creates ~/.faltoobot/config.toml with defaults. You can run faltoobot update again later to upgrade Faltoobot and run migrations.
Then you can run faltoobot and faltoochat from any folder.
If uv asks you to add its tool bin directory to your PATH, run:
uv tool update-shell
For faster project and code search inside faltoochat, install ripgrep (rg) too:
# 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. Update and configure
faltoobot update
This creates ~/.faltoobot/config.toml with defaults. Edit that file directly whenever you need to change settings.
For Codex / ChatGPT OAuth, run:
faltoobot codex-login
Or set openai.api_key in ~/.faltoobot/config.toml.
Example config:
[openai]
api_key = "your_key_here"
oauth = ""
model = "gpt-5.6-sol"
thinking = "high"
fast = false
websocket = true
[bot]
allow_group_chats = ["120363000000000000@g.us"]
allowed_chats = ["15551234567"]
bot_name = "Faltoo"
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.
To use other models through OpenRouter, set model under [openai] to an OpenRouter model id such as "anthropic/claude-sonnet-5.5" and set openrouter.api_key (or OPENROUTER_API_KEY). Any model with a / goes to OpenRouter over HTTP streaming; native image generation and compaction (including /compact) are OpenAI-only.
By default, websocket = true uses the Responses API WebSocket mode for lower-latency tool loops with either an API key or ChatGPT/Codex OAuth. Set it to false to use normal HTTP streaming.
Set allowed_chats to the WhatsApp phone numbers that should be allowed to it in direct chats. Use WhatsApp phone numbers or JIDs. Faltoobot normalizes phone numbers into WhatsApp JIDs when saving the config.
Set allow_group_chats to the group JIDs that the bot should keep history for and reply in. If a non-approved group mentions the bot, Faltoobot DMs allowed_chats with /approve_group <group_jid> and /deny_group <group_jid> instructions. In groups with more than two people, the bot replies only when mentioned or when someone replies to the bot.
2. Start WhatsApp service
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
faltoobot logs
Commands
faltoobot update
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
faltoobot whatsapp
Best command for normal use. It runs update, refreshes the background service, and follows logs.
faltoobot logs
faltoobot logs
Shows log output in follow mode.
faltoobot whatsapp-login
faltoobot whatsapp-login
Reruns WhatsApp linking. Use it to scan the Link Device QR code again.
faltoobot codex-login
faltoobot codex-login
Signs in with Codex / ChatGPT OAuth and saves the auth file path in ~/.faltoobot/config.toml.
To change other settings, edit ~/.faltoobot/config.toml directly.
Terminal chat
You can also use Faltoobot locally in the terminal.
Interactive mode
Run faltoochat with no prompt to open the terminal UI:
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:
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:
faltoochat "List new emails for the user" --workspace=./emails --notify=code@main
Commands inside chat
On WhatsApp:
/help
/reset
/status
In terminal chat:
/reset
/status
/tree
Custom terminal slash commands are loaded from ~/.faltoobot/prompts/*.md. For example, ~/.faltoobot/prompts/switch.md is available as /switch. Arguments are substituted as $1, $2, and $*, so /switch somebranch can expand $1 to somebranch.
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:
cd website
npm install
npm run dev
Build the static site locally:
cd website
npm run build
Tests
Run the full test suite with coverage:
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/.
1 maintainer
Metadata
1 maintainer
Release files for faltoobot 7.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| faltoobot-7.7.1.tar.gz | 252.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| faltoobot-7.7.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 429.6 kB
Release files / faltoobot-7.7.1.tar.gz
| Download URL | faltoobot-7.7.1.tar.gz |
|---|---|
| Size | 252.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
150c90e02ba9d40bbb855c61222f1bba86eb379adc636383b8160a42a30e3e7b
|
|
BLAKE2b-256 checksum How to use checksums |
72b5eb84eca62cfc7db360abc75a46187748af2dfaf08a8e93fbd69edebe377b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / faltoobot-7.7.1-py3-none-any.whl
| Download URL | faltoobot-7.7.1-py3-none-any.whl |
|---|---|
| Size | 176.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a2490d6a4d6cd6959abd6c235b6e477d971847ea268f77bac958af01dbb7e48
|
|
BLAKE2b-256 checksum How to use checksums |
17804f1c3bdf48a88ca973ba39cd032303d5f785ac67691651faf40cfc133778
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
