doit-fm

A background AI agent that lets you control your computer via Telegram.

How it works

Telegram message → long-polling → AI model → structured JSON → OS tool → result → Telegram reply

You send a natural language message. The AI maps it to a tool + args. The tool runs as a real OS action. The result comes back to you in Telegram. In 2–5 seconds.

Install

pip install doit-fm

Or from source:

git clone <repo>
cd doit-fm
pip install -e .

Setup

doitfm init

The wizard walks you through:

1. Checking dependencies
2. Choosing AI provider + model (free options: Groq, OpenRouter, Ollama)
3. Connecting your Telegram bot
4. Sending a test message

Run

doitfm run

Background:

nohup doitfm run &

Commands

doitfm init     — Setup wizard
doitfm run      — Start the agent
doitfm stop     — Stop the agent
doitfm status   — Check if running
doitfm doctor   — Diagnostics

Telegram commands

/health         — CPU, RAM, disk, battery
/ps             — Running processes
/disk           — Disk partitions
/ip             — Public IP
/time           — Date and time
/weather <city> — Weather
/volume [0-100] — Get/set volume
/ls [path]      — List directory
/run <cmd>      — Shell command (with confirmation)
/notes          — List notes
/note <text>    — Save note
/clear          — Clear AI conversation memory
/status         — Agent status
/help           — Help

Or just talk naturally:

• "how's my system?"
• "what's the weather in Tokyo?"
• "remind me to call John in 30 minutes"
• "what's using all my CPU?"
• "take a screenshot"
• "what's my public IP?"
• "calculate 847 * 23"

AI Providers

Tools

Security

• Only your Telegram user ID can control the agent
• All other messages are silently rejected
• Dangerous tools require explicit tap-to-confirm via inline buttons
• API key is encrypted at rest (Fernet symmetric encryption)
• Encryption key stored at ~/.local/share/doit-fm/data/.enc_key (chmod 600)

Architecture

src/doitfm/
├── __init__.py   — package metadata
├── config.py     — constants, paths, provider registry
├── store.py      — encrypted config file (singleton)
├── tools.py      — 35 tool implementations + registry + dispatcher
├── ai.py         — AIEngine + ConversationMemory
├── bot.py        — TelegramAPI + TelegramBot
└── cli.py        — Click CLI

Adding a new tool

1. Write an async function in tools.py — takes **kwargs, returns dict, never raises
2. Add one entry to TOOLS dict
3. Add one intent rule to the system prompt in ai.py
4. Optionally add a slash command in bot.py

Adding a new AI provider

1. Add entry to AI_PROVIDERS in config.py
2. If not OpenAI-compatible, add a branch in AIEngine in ai.py

License

MIT