bysalim 1.0.0

BySalim — AI agent that controls your computer via Telegram

📱 BySalim

BySalim 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

pip install bysalim

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

Background daemon

nohup bysalim run &

Stop / check

bysalim stop
bysalim status
bysalim doctor   # full diagnostic

---

CLI Reference

Command	Description
bysalim init	Interactive setup wizard
bysalim init --reconfigure	Re-run setup (overwrites existing config)
bysalim run	Start the agent (foreground)
bysalim run --background	Start as a background daemon
bysalim stop	Gracefully stop the agent
bysalim status	Show running status and config summary
bysalim 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/bysalim/data/
• macOS: ~/Library/Application Support/bysalim/data/
• Windows: %APPDATA%\bysalim\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 bysalim init)
• A Telegram bot token (free, from @BotFather)
• An API key for your chosen AI provider

---

License

MIT