flowly-ai 1.0.0

A lightweight personal AI assistant framework

Flowly AI

Your personal AI that runs locally, talks everywhere.

---

Flowly is a personal AI assistant that lives on your machine. Connect it to Telegram, WhatsApp, Discord, or Slack — then talk to it from anywhere. It can browse the web, manage files, run shell commands, take screenshots, schedule tasks, make phone calls, and more.

You (Telegram) → Flowly (your Mac/PC) → tools, files, APIs → response

Why Flowly?

• Runs on your machine — your data stays local, your tools stay private
• Always on — install as a background service, survives terminal close and reboot
• Multi-channel — one agent, reachable from Telegram, WhatsApp, Discord, Slack
• Voice calls — answer phone calls with Twilio, talk with real-time STT/TTS
• Extensible — add tools, skills, personas, or entire channel adapters
• Cross-platform — macOS (launchd), Linux (systemd), Windows (Task Scheduler)
• Multi-provider — OpenRouter, Anthropic, OpenAI, xAI/Grok, Gemini, and more via LiteLLM

Quick Start

1. Install

With uv (recommended)

uv tool install flowly-ai

From PyPI

pip install flowly-ai

From source (development)

git clone https://github.com/hakansoren/flowlyai.git && cd flowlyai
pip install -e .

2. Setup

flowly onboard          # Initialize config & workspace
flowly setup            # Interactive setup wizard (API keys, channels, tools)

3. Run

flowly agent -m "What can you do?"   # Single message
flowly agent                          # Interactive chat
flowly gateway                        # Start all channels

API keys: Get your OpenRouter key, then run flowly setup or edit ~/.flowly/config.json directly. Optional: Groq (voice), Brave Search (web search).

Architecture

┌─────────────────────────────────────────────┐
│                  Gateway                     │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │ Telegram │  │ WhatsApp │  │  Discord   │  │
│  │  Slack   │  │  Voice   │  │   CLI      │  │
│  └────┬─────┘  └────┬─────┘  └─────┬─────┘  │
│       └──────────────┼──────────────┘        │
│                      ▼                       │
│              ┌──────────────┐                │
│              │  Agent Loop  │                │
│              │   (LiteLLM)  │                │
│              └──────┬───────┘                │
│                     ▼                        │
│  ┌─────┐ ┌──────┐ ┌─────┐ ┌──────┐ ┌─────┐ │
│  │Shell│ │ Web  │ │File │ │ Cron │ │ ... │ │
│  └─────┘ └──────┘ └─────┘ └──────┘ └─────┘ │
│                                              │
│  ┌──────────────────────────────────────┐    │
│  │  Skills · Personas · Hub · Memory    │    │
│  └──────────────────────────────────────┘    │
└─────────────────────────────────────────────┘

Built-in Tools

Tool	What it does
Shell	Run commands on your machine (sandboxed)
Filesystem	Read, write, edit, list files and directories
Web Search	Search the web with Brave Search API
Web Fetch	Fetch and extract content from URLs
Screenshot	Capture your screen
Cron	Schedule recurring or one-time tasks
Docker	Manage containers and images
Trello	Create and manage boards, lists, cards
X (Twitter)	Post tweets, search, read timelines, get profiles
System	CPU, memory, disk, process monitoring
Voice	Make and receive phone calls via Twilio
Message	Send messages across channels
Spawn	Run background sub-agents

Channels

Connect Flowly to your favorite chat apps. Each channel runs simultaneously through the gateway.

Telegram — easiest setup

1. Create a bot via @BotFather on Telegram
2. Add to config:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

3. flowly gateway

Get your user ID from @userinfobot.

WhatsApp — scan QR

flowly channels login    # Scan QR code
flowly gateway           # Start (in another terminal)

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["[phone]"]
    }
  }
}

Requires Node.js ≥18.

Discord

1. Create app at Discord Developer Portal
2. Enable Message Content Intent under Privileged Gateway Intents
3. Generate invite URL with bot scope + Send Messages + Read Message History

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

Slack

1. Create app at api.slack.com/apps
2. Enable Socket Mode, add bot scopes: chat:write, app_mentions:read, im:history
3. Subscribe to events: message.im, app_mention

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "groupPolicy": "mention"
    }
  }
}

No public URL needed — Socket Mode connects outbound.

Providers

Flowly uses LiteLLM under the hood, giving you access to 100+ LLM models. Configure your preferred provider:

Provider	Model prefix	Config key
OpenRouter	anthropic/claude-*, openai/gpt-*, ...	providers.openrouter.apiKey
Anthropic	claude-*	providers.anthropic.apiKey
OpenAI	gpt-*, o1-*	providers.openai.apiKey
xAI	xai/grok-*	providers.xai.apiKey
Google Gemini	gemini/*	providers.gemini.apiKey
Zhipu	zhipu/*	providers.zhipu.apiKey
vLLM (self-hosted)	any	providers.vllm.apiBase
Groq (voice STT)	—	providers.groq.apiKey

Example: Switch to Grok

{
  "providers": {
    "xai": { "apiKey": "xai-..." }
  },
  "agents": {
    "defaults": { "model": "xai/grok-4" }
  }
}

Skills

Skills are plug-and-play capability packs. Install from the hub or create your own:

flowly skills list                   # List installed
flowly skills search weather         # Search hub
flowly skills install weather        # Install

Skill	What it does
github	Interact with GitHub via gh CLI
weather	Weather forecasts (wttr.in + Open-Meteo)
summarize	Summarize URLs, files, YouTube videos
tmux	Remote control tmux sessions
skill-creator	Generate new skills from description

Create your own: drop a SKILL.md file in ~/.flowly/workspace/skills/your-skill/.

Security

Command Execution Sandbox

Flowly's shell tool uses a configurable security sandbox:

Mode	Behavior
deny	All commands blocked (default)
allowlist	Only approved patterns run; unknown commands are asked or denied
full	All commands allowed (use with caution)

Ask modes (for allowlist):

• on-miss — ask the user via chat when a command isn't in the allowlist (recommended)
• always — ask for every command
• off — silently deny unknown commands

flowly setup              # Configure via wizard
flowly approvals status   # View current config
flowly approvals list     # View allowlist

Device Pairing

Channels use a pairing system to authorize users:

flowly pairing list               # Pending requests
flowly pairing approve telegram CODE  # Approve
flowly pairing revoke telegram USER   # Revoke
flowly pairing allowed telegram       # List allowed

Background Service

Run Flowly as a persistent service — survives terminal close and auto-starts on boot:

flowly service install --start    # Install and start
flowly service status             # Health check
flowly service logs -f            # Follow logs
flowly service restart            # Restart
flowly service stop               # Stop
flowly service uninstall          # Remove

Platform	Backend
macOS	launchd (LaunchAgents)
Linux	systemd (user service)
Windows	Task Scheduler

Personas

Switch how Flowly talks without changing functionality:

flowly persona list              # See all
flowly persona set jarvis        # Switch persona
flowly service restart           # Apply

Persona	Style
default	Helpful and friendly
jarvis	J.A.R.V.I.S. — British AI, dry wit
friday	F.R.I.D.A.Y. — warm, professional
pirate	"Aye aye, Captain!"
samurai	Brief and wise
casual	Your best buddy
professor	Step-by-step explanations
butler	Distinguished, ultra-polite

Create your own: drop a .md file in ~/.flowly/workspace/personas/.

Voice Calls

Flowly can answer and make phone calls with real-time speech:

flowly setup              # Configure Twilio + STT/TTS
flowly gateway            # Start with voice enabled

Supported providers:

• STT: Groq Whisper, Deepgram, OpenAI, ElevenLabs
• TTS: ElevenLabs, Deepgram, OpenAI
• Telephony: Twilio

CLI Reference

Setup & Config
  flowly onboard                   Initialize config & workspace
  flowly setup                     Interactive setup wizard
  flowly status                    Overall system status

Agent
  flowly agent -m "..."            Send a single message
  flowly agent                     Interactive chat mode
  flowly gateway                   Start gateway (all channels)
  flowly gateway --persona jarvis  Start with a persona

Service
  flowly service install --start   Install and start background service
  flowly service status            Health check
  flowly service logs -f           Follow logs
  flowly service restart           Restart service
  flowly service stop / uninstall  Stop or remove

Channels
  flowly channels login            Link WhatsApp (QR code)
  flowly channels status           Channel connection status

Personas
  flowly persona list              List all personas
  flowly persona set <name>        Switch active persona
  flowly persona show <name>       View persona details

Skills
  flowly skills list               List installed skills
  flowly skills search <query>     Search skill hub
  flowly skills install <name>     Install a skill
  flowly skills remove <name>      Remove a skill

Scheduling
  flowly cron list                 List scheduled jobs
  flowly cron add                  Add a new job
  flowly cron remove <id>          Remove a job
  flowly cron run <id>             Manually run a job

Security
  flowly approvals status          Exec sandbox config
  flowly approvals list            View allowlist
  flowly approvals add <pattern>   Add allowlist pattern
  flowly approvals remove <id>     Remove allowlist entry
  flowly pairing list              Pending pairing requests
  flowly pairing approve <ch> <code>  Approve user
  flowly pairing revoke <ch> <user>   Revoke access

Configuration

All config lives in ~/.flowly/config.json (camelCase keys):

{
  "providers": {
    "openrouter": { "apiKey": "sk-or-v1-..." },
    "xai": { "apiKey": "xai-..." },
    "groq": { "apiKey": "gsk_..." }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5",
      "maxTokens": 16384,
      "temperature": 0.7,
      "persona": "default"
    }
  },
  "channels": {
    "telegram": { "enabled": true, "token": "...", "dmPolicy": "pairing" },
    "discord": { "enabled": true, "token": "..." },
    "slack": { "enabled": true, "botToken": "xoxb-...", "appToken": "xapp-..." },
    "whatsapp": { "enabled": true }
  },
  "tools": {
    "web": { "search": { "braveApiKey": "..." } },
    "exec": {
      "enabled": true,
      "security": "allowlist",
      "ask": "on-miss"
    }
  },
  "integrations": {
    "trello": { "apiKey": "...", "token": "..." },
    "x": {
      "bearerToken": "...",
      "apiKey": "...", "apiSecret": "...",
      "accessToken": "...", "accessTokenSecret": "..."
    },
    "voice": { "enabled": true, "twilioAccountSid": "...", "twilioAuthToken": "..." }
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790
  }
}

Project Structure

flowly/
├── agent/              # Core agent loop, context, memory
│   └── tools/          # Built-in tools (shell, web, file, cron, ...)
├── channels/           # Chat platform adapters (Telegram, Discord, ...)
├── providers/          # LLM provider abstraction (LiteLLM)
├── cli/                # CLI commands and setup wizard
├── config/             # Configuration schema and loader
├── cron/               # Task scheduling service
├── session/            # Conversation session management
├── bus/                # Event bus for message routing
├── heartbeat/          # Periodic wake-up service
└── utils/              # Cross-platform utilities

Requirements

	Minimum
Python	≥ 3.11
Node.js	≥ 18 (only for WhatsApp bridge)
OS	macOS, Linux, or Windows

Desktop App

Flowly Desktop — Electron app with guided setup, one-click install, and visual management.

Contributing

Contributions are welcome! Flowly is designed to be readable and extensible:

• Add a tool: Create a class extending Tool in flowly/agent/tools/, register it in loop.py
• Add a channel: Implement BaseChannel in flowly/channels/
• Add a provider: Add detection logic in flowly/providers/litellm_provider.py
• Add a skill: Drop a SKILL.md in a new folder under ~/.flowly/workspace/skills/

Please open an issue first for large changes.

---

Changelog

2026-02-11 — X API, command execution setup, Apache 2.0

• X (Twitter) API integration (post, search, timeline, profiles)
• xAI/Grok as LiteLLM provider
• Command execution setup wizard
• Cron job results injected into user session
• License changed to Apache 2.0

2026-02-10 — Discord & Slack channels, setup wizard

• Discord and Slack channel implementations
• Interactive CLI setup wizard (flowly setup)
• Multi-channel manager support

2026-02-09 — Service mode, personas, screenshot delegation

• Background service mode (launchd/systemd/schtasks)
• 8 built-in personas (Jarvis, Friday, Pirate, etc.)
• Electron-delegated screenshot system
• Voice call improvements

2026-02-06 — Integrated voice system, new tools

• Twilio voice bridge with real-time audio streaming
• ElevenLabs, Deepgram, Groq Whisper STT/TTS providers
• Agentic voice call state machine
• System monitoring, Docker, Trello integration tools
• Cross-platform support (Windows/macOS/Linux)

2026-02-04 — Secure execution, pairing system

• Secure command execution sandbox
• Device pairing system
• Interactive setup CLI wizard

2026-02-03 — Initial release

• Core agent loop with LiteLLM provider
• Telegram and WhatsApp channels
• Cron scheduling, context compaction
• Groq Whisper voice transcription
• Flowly Hub skill management

---

_{Apache License 2.0 · Copyright 2025-2026 Nocetic Limited}