flowly-code 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. flowly_code/__init__.py +30 -0
  2. flowly_code/__main__.py +8 -0
  3. flowly_code/activity/__init__.py +1 -0
  4. flowly_code/activity/bus.py +91 -0
  5. flowly_code/activity/events.py +40 -0
  6. flowly_code/agent/__init__.py +8 -0
  7. flowly_code/agent/context.py +485 -0
  8. flowly_code/agent/loop.py +1349 -0
  9. flowly_code/agent/memory.py +109 -0
  10. flowly_code/agent/skills.py +259 -0
  11. flowly_code/agent/subagent.py +249 -0
  12. flowly_code/agent/tools/__init__.py +6 -0
  13. flowly_code/agent/tools/base.py +55 -0
  14. flowly_code/agent/tools/delegate.py +194 -0
  15. flowly_code/agent/tools/dispatch.py +840 -0
  16. flowly_code/agent/tools/docker.py +609 -0
  17. flowly_code/agent/tools/filesystem.py +280 -0
  18. flowly_code/agent/tools/mcp.py +85 -0
  19. flowly_code/agent/tools/message.py +235 -0
  20. flowly_code/agent/tools/registry.py +257 -0
  21. flowly_code/agent/tools/screenshot.py +444 -0
  22. flowly_code/agent/tools/shell.py +166 -0
  23. flowly_code/agent/tools/spawn.py +65 -0
  24. flowly_code/agent/tools/system.py +917 -0
  25. flowly_code/agent/tools/trello.py +420 -0
  26. flowly_code/agent/tools/web.py +139 -0
  27. flowly_code/agent/tools/x.py +399 -0
  28. flowly_code/bus/__init__.py +6 -0
  29. flowly_code/bus/events.py +37 -0
  30. flowly_code/bus/queue.py +81 -0
  31. flowly_code/channels/__init__.py +6 -0
  32. flowly_code/channels/base.py +121 -0
  33. flowly_code/channels/manager.py +135 -0
  34. flowly_code/channels/telegram.py +1132 -0
  35. flowly_code/cli/__init__.py +1 -0
  36. flowly_code/cli/commands.py +1831 -0
  37. flowly_code/cli/setup.py +1356 -0
  38. flowly_code/compaction/__init__.py +39 -0
  39. flowly_code/compaction/estimator.py +88 -0
  40. flowly_code/compaction/pruning.py +223 -0
  41. flowly_code/compaction/service.py +297 -0
  42. flowly_code/compaction/summarizer.py +384 -0
  43. flowly_code/compaction/types.py +71 -0
  44. flowly_code/config/__init__.py +6 -0
  45. flowly_code/config/loader.py +102 -0
  46. flowly_code/config/schema.py +324 -0
  47. flowly_code/exec/__init__.py +39 -0
  48. flowly_code/exec/approvals.py +288 -0
  49. flowly_code/exec/executor.py +184 -0
  50. flowly_code/exec/safety.py +247 -0
  51. flowly_code/exec/types.py +88 -0
  52. flowly_code/gateway/__init__.py +5 -0
  53. flowly_code/gateway/server.py +103 -0
  54. flowly_code/heartbeat/__init__.py +5 -0
  55. flowly_code/heartbeat/service.py +130 -0
  56. flowly_code/multiagent/README.md +248 -0
  57. flowly_code/multiagent/__init__.py +1 -0
  58. flowly_code/multiagent/invoke.py +210 -0
  59. flowly_code/multiagent/orchestrator.py +156 -0
  60. flowly_code/multiagent/router.py +156 -0
  61. flowly_code/multiagent/setup.py +171 -0
  62. flowly_code/pairing/__init__.py +21 -0
  63. flowly_code/pairing/store.py +343 -0
  64. flowly_code/providers/__init__.py +6 -0
  65. flowly_code/providers/base.py +69 -0
  66. flowly_code/providers/litellm_provider.py +178 -0
  67. flowly_code/providers/transcription.py +64 -0
  68. flowly_code/session/__init__.py +5 -0
  69. flowly_code/session/manager.py +249 -0
  70. flowly_code/skills/README.md +24 -0
  71. flowly_code/skills/compact/SKILL.md +27 -0
  72. flowly_code/skills/github/SKILL.md +48 -0
  73. flowly_code/skills/skill-creator/SKILL.md +371 -0
  74. flowly_code/skills/summarize/SKILL.md +67 -0
  75. flowly_code/skills/tmux/SKILL.md +121 -0
  76. flowly_code/skills/tmux/scripts/find-sessions.sh +112 -0
  77. flowly_code/skills/tmux/scripts/wait-for-text.sh +83 -0
  78. flowly_code/skills/weather/SKILL.md +49 -0
  79. flowly_code/utils/__init__.py +5 -0
  80. flowly_code/utils/helpers.py +91 -0
  81. flowly_code-1.0.0.dist-info/METADATA +724 -0
  82. flowly_code-1.0.0.dist-info/RECORD +86 -0
  83. flowly_code-1.0.0.dist-info/WHEEL +4 -0
  84. flowly_code-1.0.0.dist-info/entry_points.txt +2 -0
  85. flowly_code-1.0.0.dist-info/licenses/LICENSE +191 -0
  86. flowly_code-1.0.0.dist-info/licenses/NOTICE +74 -0
@@ -0,0 +1,724 @@
1
+ Metadata-Version: 2.4
2
+ Name: flowly-code
3
+ Version: 1.0.0
4
+ Summary: Personal AI assistant that runs locally and connects to Telegram, Discord, Slack, and more.
5
+ Project-URL: Homepage, https://flowly.ai
6
+ Project-URL: Documentation, https://github.com/nocetic/flowly-code#readme
7
+ Project-URL: Repository, https://github.com/nocetic/flowly-code
8
+ Project-URL: Issues, https://github.com/nocetic/flowly-code/issues
9
+ Project-URL: Changelog, https://github.com/nocetic/flowly-code#changelog
10
+ Author-email: Nocetic Limited <hello@nocetic.com>
11
+ Maintainer-email: Nocetic Limited <hello@nocetic.com>
12
+ License: Apache-2.0
13
+ License-File: LICENSE
14
+ License-File: NOTICE
15
+ Keywords: agent,ai,assistant,chatbot,coding,discord,llm,slack,telegram
16
+ Classifier: Development Status :: 4 - Beta
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: License :: OSI Approved :: Apache Software License
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Communications :: Chat
24
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
25
+ Classifier: Typing :: Typed
26
+ Requires-Python: >=3.11
27
+ Requires-Dist: aiohttp>=3.9.0
28
+ Requires-Dist: filelock>=3.0.0
29
+ Requires-Dist: httpx>=0.25.0
30
+ Requires-Dist: inquirerpy>=0.3.4
31
+ Requires-Dist: litellm>=1.0.0
32
+ Requires-Dist: loguru>=0.7.0
33
+ Requires-Dist: mcp>=1.0.0
34
+ Requires-Dist: pydantic-settings>=2.0.0
35
+ Requires-Dist: pydantic>=2.0.0
36
+ Requires-Dist: python-multipart>=0.0.6
37
+ Requires-Dist: python-telegram-bot>=21.0
38
+ Requires-Dist: readability-lxml>=0.8.0
39
+ Requires-Dist: rich>=13.0.0
40
+ Requires-Dist: starlette>=0.32.0
41
+ Requires-Dist: tiktoken>=0.5.0
42
+ Requires-Dist: typer>=0.9.0
43
+ Requires-Dist: uvicorn>=0.24.0
44
+ Requires-Dist: websocket-client>=1.6.0
45
+ Requires-Dist: websockets>=12.0
46
+ Provides-Extra: dev
47
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
48
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
49
+ Requires-Dist: ruff>=0.1.0; extra == 'dev'
50
+ Description-Content-Type: text/markdown
51
+
52
+ <div align="center">
53
+ <img src="flowly_logo.svg" alt="Flowly" width="150">
54
+ <h1>Flowly AI</h1>
55
+ <p><strong>Your personal AI that runs locally, talks everywhere.</strong></p>
56
+ <p>
57
+ <a href="https://pypi.org/project/flowly-ai/"><img src="https://img.shields.io/pypi/v/flowly-ai" alt="PyPI"></a>
58
+ <img src="https://img.shields.io/badge/python-≥3.11-3776AB?logo=python&logoColor=white" alt="Python">
59
+ <img src="https://img.shields.io/badge/platform-macOS%20·%20Linux%20·%20Windows-lightgrey" alt="Platform">
60
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
61
+ </p>
62
+ </div>
63
+
64
+ ---
65
+
66
+ 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.
67
+
68
+ ```
69
+ You (Telegram) → Flowly (your Mac/PC) → tools, files, APIs → response
70
+ ```
71
+
72
+ ## Why Flowly?
73
+
74
+ - **Runs on your machine** — your data stays local, your tools stay private
75
+ - **Always on** — install as a background service, survives terminal close and reboot
76
+ - **Multi-agent** — create custom agents backed by Claude Code or Codex, build teams, delegate tasks
77
+ - **Multi-channel** — one agent, reachable from Telegram, WhatsApp, Discord, Slack
78
+ - **Voice calls** — answer phone calls with Twilio, talk with real-time STT/TTS
79
+ - **Extensible** — add tools, skills, personas, or entire channel adapters
80
+ - **Cross-platform** — macOS (launchd), Linux (systemd), Windows (Task Scheduler)
81
+ - **Multi-provider** — OpenRouter, Anthropic, OpenAI, xAI/Grok, Gemini, and more via LiteLLM
82
+
83
+ ## Quick Start
84
+
85
+ ### 1. Install
86
+
87
+ **With [uv](https://github.com/astral-sh/uv)** (recommended)
88
+
89
+ ```bash
90
+ uv tool install flowly-ai
91
+ ```
92
+
93
+ **From PyPI**
94
+
95
+ ```bash
96
+ pip install flowly-ai
97
+ ```
98
+
99
+ **From source** (development)
100
+
101
+ ```bash
102
+ git clone https://github.com/hakansoren/flowlyai.git && cd flowlyai
103
+ pip install -e .
104
+ ```
105
+
106
+ ### 2. Setup
107
+
108
+ ```bash
109
+ flowly onboard # Initialize config & workspace
110
+ flowly setup # Interactive setup wizard (API keys, channels, tools)
111
+ ```
112
+
113
+ ### 3. Run
114
+
115
+ ```bash
116
+ flowly agent -m "What can you do?" # Single message
117
+ flowly agent # Interactive chat
118
+ flowly gateway # Start all channels
119
+ ```
120
+
121
+ > **API keys:** Get your [OpenRouter](https://openrouter.ai/keys) key, then run `flowly setup` or edit `~/.flowly/config.json` directly. Optional: [Groq](https://console.groq.com/keys) (voice), [Brave Search](https://brave.com/search/api/) (web search).
122
+
123
+ ## Architecture
124
+
125
+ ```
126
+ ┌─────────────────────────────────────────────┐
127
+ │ Gateway │
128
+ │ │
129
+ │ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
130
+ │ │ Telegram │ │ WhatsApp │ │ Discord │ │
131
+ │ │ Slack │ │ Voice │ │ CLI │ │
132
+ │ └────┬─────┘ └────┬─────┘ └─────┬─────┘ │
133
+ │ └──────────────┼──────────────┘ │
134
+ │ ▼ │
135
+ │ ┌──────────────┐ │
136
+ │ │ Agent Loop │ │
137
+ │ │ (LiteLLM) │ │
138
+ │ └──────┬───────┘ │
139
+ │ ▼ │
140
+ │ ┌─────┐ ┌──────┐ ┌─────┐ ┌──────┐ ┌─────┐ │
141
+ │ │Shell│ │ Web │ │File │ │ Cron │ │ ... │ │
142
+ │ └─────┘ └──────┘ └─────┘ └──────┘ └─────┘ │
143
+ │ │
144
+ │ ┌──────────────────────────────────────┐ │
145
+ │ │ Skills · Personas · Hub · Memory │ │
146
+ │ └──────────────────────────────────────┘ │
147
+ └─────────────────────────────────────────────┘
148
+ ```
149
+
150
+ ## Multi-Agent
151
+
152
+ Flowly can delegate tasks to external AI agents like [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [OpenCode](https://github.com/opencode-ai/opencode), or [Droid](https://github.com/Factory-AI/factory). Each agent runs as a CLI subprocess in the background — Flowly sends the task, responds to you immediately, and delivers the result when the agent finishes.
153
+
154
+ ### Setup
155
+
156
+ ```bash
157
+ flowly setup agents # Interactive wizard — add agents, create teams
158
+ ```
159
+
160
+ Or edit `~/.flowly/config.json` directly:
161
+
162
+ ```json
163
+ {
164
+ "agents": {
165
+ "defaults": { "model": "anthropic/claude-sonnet-4-5" },
166
+ "agents": {
167
+ "coder": {
168
+ "name": "Code Assistant",
169
+ "provider": "anthropic",
170
+ "model": "sonnet"
171
+ },
172
+ "reviewer": {
173
+ "name": "Code Reviewer",
174
+ "provider": "openai",
175
+ "model": "gpt-5.3-codex"
176
+ }
177
+ },
178
+ "teams": {
179
+ "dev": {
180
+ "name": "Development Team",
181
+ "agents": ["coder", "reviewer"],
182
+ "leaderAgent": "coder"
183
+ }
184
+ }
185
+ }
186
+ }
187
+ ```
188
+
189
+ **Requirements:** Install the CLI tool for each provider:
190
+
191
+ | Provider | CLI Required | Model names |
192
+ |----------|-------------|-------------|
193
+ | `anthropic` | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`) | `sonnet`, `opus`, `haiku` |
194
+ | `openai` | [Codex](https://github.com/openai/codex) (`codex`) | `gpt-5.3-codex`, `gpt-5.2` |
195
+ | `gemini` | [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini`) | `gemini-3-pro`, `gemini-3-flash`, `gemini-2.5-pro`, `gemini-2.5-flash` |
196
+ | `opencode` | [OpenCode](https://github.com/opencode-ai/opencode) (`opencode`) | `anthropic/claude-sonnet-4-5`, `openai/gpt-4o`, ... |
197
+ | `droid` | [Droid](https://github.com/Factory-AI/factory) (`droid`) | `opus`, `sonnet`, `gpt-5` |
198
+
199
+ ### Usage
200
+
201
+ **`@mention`** — prefix your message with `@agent_id` to talk to a specific agent:
202
+
203
+ ```
204
+ @coder fix the login bug in auth.py
205
+ @reviewer review the last PR
206
+ ```
207
+
208
+ **`@team`** — mention a team name to reach its leader agent:
209
+
210
+ ```
211
+ @dev fix the auth bug → routes to "coder" (team leader)
212
+ ```
213
+
214
+ **Natural language** — or just ask Flowly, and it decides whether to delegate:
215
+
216
+ ```
217
+ You: build me a todo app with Flask
218
+ Flowly: I'll delegate this to @coder...
219
+ [coder works in the background — you can keep chatting]
220
+ Flowly: @coder finished! Here's what was built: ...
221
+ ```
222
+
223
+ ### How It Works
224
+
225
+ 1. **Routing**: `@mention` messages are parsed by `AgentRouter` — `@agent_id` routes to that agent, `@team_id` routes to the team's leader agent.
226
+ 2. **Fire-and-forget**: The `delegate_to` tool starts a CLI subprocess in the background and returns immediately — you can keep chatting while the agent works.
227
+ 3. **Team chains**: When routed via `@team`, the leader runs first. If its response contains `[@teammate: message]`, the orchestrator automatically invokes that teammate, creating a sequential chain (up to 10 steps).
228
+ 4. **Fan-out**: If an agent mentions multiple teammates (`[@coder: ...] [@tester: ...]`), all are invoked in parallel via `asyncio.gather`.
229
+ 5. **Result delivery**: When the subprocess finishes, the result is sent back through the main agent (via the message bus), which summarizes it for you.
230
+ 6. **Loop prevention**: Delegate results are marked with `[DELEGATE_RESULT:]` — when processing these, the `delegate_to` tool is temporarily removed to prevent infinite re-delegation.
231
+
232
+ > For full orchestrator internals, see [`multiagent/README.md`](flowly_code/multiagent/README.md).
233
+
234
+ ## Built-in Tools
235
+
236
+ | Tool | What it does |
237
+ |------|-------------|
238
+ | **Shell** | Run commands on your machine (sandboxed) |
239
+ | **Filesystem** | Read, write, edit, list files and directories |
240
+ | **Web Search** | Search the web with Brave Search API |
241
+ | **Web Fetch** | Fetch and extract content from URLs |
242
+ | **Screenshot** | Capture your screen |
243
+ | **Cron** | Schedule recurring or one-time tasks |
244
+ | **Docker** | Manage containers and images |
245
+ | **Trello** | Create and manage boards, lists, cards |
246
+ | **X (Twitter)** | Post tweets, search, read timelines, get profiles |
247
+ | **System** | CPU, memory, disk, process monitoring |
248
+ | **Voice** | Make and receive phone calls via Twilio |
249
+ | **Message** | Send messages across channels |
250
+ | **Delegate** | Delegate tasks to other agents (Claude Code, Codex, etc.) |
251
+ | **Spawn** | Run background sub-agents |
252
+
253
+ ## Channels
254
+
255
+ Connect Flowly to your favorite chat apps. Each channel runs simultaneously through the gateway.
256
+
257
+ <details>
258
+ <summary><b>Telegram</b> — easiest setup</summary>
259
+
260
+ 1. Create a bot via `@BotFather` on Telegram
261
+ 2. Add to config:
262
+
263
+ ```json
264
+ {
265
+ "channels": {
266
+ "telegram": {
267
+ "enabled": true,
268
+ "token": "YOUR_BOT_TOKEN",
269
+ "allowFrom": ["YOUR_USER_ID"]
270
+ }
271
+ }
272
+ }
273
+ ```
274
+
275
+ 3. `flowly gateway`
276
+
277
+ > Get your user ID from `@userinfobot`.
278
+
279
+ </details>
280
+
281
+ <details>
282
+ <summary><b>WhatsApp</b> — scan QR</summary>
283
+
284
+ ```bash
285
+ flowly channels login # Scan QR code
286
+ flowly gateway # Start (in another terminal)
287
+ ```
288
+
289
+ ```json
290
+ {
291
+ "channels": {
292
+ "whatsapp": {
293
+ "enabled": true,
294
+ "allowFrom": ["+1234567890"]
295
+ }
296
+ }
297
+ }
298
+ ```
299
+
300
+ Requires Node.js ≥18.
301
+
302
+ </details>
303
+
304
+ <details>
305
+ <summary><b>Discord</b></summary>
306
+
307
+ 1. Create app at [Discord Developer Portal](https://discord.com/developers/applications)
308
+ 2. Enable **Message Content Intent** under Privileged Gateway Intents
309
+ 3. Generate invite URL with `bot` scope + `Send Messages` + `Read Message History`
310
+
311
+ ```json
312
+ {
313
+ "channels": {
314
+ "discord": {
315
+ "enabled": true,
316
+ "token": "YOUR_BOT_TOKEN",
317
+ "allowFrom": ["YOUR_USER_ID"]
318
+ }
319
+ }
320
+ }
321
+ ```
322
+
323
+ </details>
324
+
325
+ <details>
326
+ <summary><b>Slack</b></summary>
327
+
328
+ 1. Create app at [api.slack.com/apps](https://api.slack.com/apps)
329
+ 2. Enable Socket Mode, add bot scopes: `chat:write`, `app_mentions:read`, `im:history`
330
+ 3. Subscribe to events: `message.im`, `app_mention`
331
+
332
+ ```json
333
+ {
334
+ "channels": {
335
+ "slack": {
336
+ "enabled": true,
337
+ "botToken": "xoxb-...",
338
+ "appToken": "xapp-...",
339
+ "groupPolicy": "mention"
340
+ }
341
+ }
342
+ }
343
+ ```
344
+
345
+ No public URL needed — Socket Mode connects outbound.
346
+
347
+ </details>
348
+
349
+ ## Providers
350
+
351
+ Flowly uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood, giving you access to 100+ LLM models. Configure your preferred provider:
352
+
353
+ | Provider | Model prefix | Config key |
354
+ |----------|-------------|------------|
355
+ | [OpenRouter](https://openrouter.ai) | `anthropic/claude-*`, `openai/gpt-*`, ... | `providers.openrouter.apiKey` |
356
+ | [Anthropic](https://console.anthropic.com) | `claude-*` | `providers.anthropic.apiKey` |
357
+ | [OpenAI](https://platform.openai.com) | `gpt-*`, `o1-*` | `providers.openai.apiKey` |
358
+ | [xAI](https://docs.x.ai) | `xai/grok-*` | `providers.xai.apiKey` |
359
+ | [Google Gemini](https://aistudio.google.com) | `gemini/*` | `providers.gemini.apiKey` |
360
+ | [Zhipu](https://open.bigmodel.cn) | `zhipu/*` | `providers.zhipu.apiKey` |
361
+ | [vLLM](https://docs.vllm.ai) (self-hosted) | any | `providers.vllm.apiBase` |
362
+ | [Groq](https://console.groq.com) (voice STT) | — | `providers.groq.apiKey` |
363
+
364
+ **Example: Switch to Grok**
365
+
366
+ ```json
367
+ {
368
+ "providers": {
369
+ "xai": { "apiKey": "xai-..." }
370
+ },
371
+ "agents": {
372
+ "defaults": { "model": "xai/grok-4" }
373
+ }
374
+ }
375
+ ```
376
+
377
+ ## Skills
378
+
379
+ Skills are plug-and-play capability packs. Install from the hub or create your own:
380
+
381
+ ```bash
382
+ flowly skills list # List installed
383
+ flowly skills search weather # Search hub
384
+ flowly skills install weather # Install
385
+ ```
386
+
387
+ | Skill | What it does |
388
+ |-------|-------------|
389
+ | **github** | Interact with GitHub via `gh` CLI |
390
+ | **weather** | Weather forecasts (wttr.in + Open-Meteo) |
391
+ | **summarize** | Summarize URLs, files, YouTube videos |
392
+ | **tmux** | Remote control tmux sessions |
393
+ | **skill-creator** | Generate new skills from description |
394
+
395
+ Create your own: drop a `SKILL.md` file in `~/.flowly/workspace/skills/your-skill/`.
396
+
397
+ ## Security
398
+
399
+ ### Command Execution Sandbox
400
+
401
+ Flowly's shell tool uses a configurable security sandbox:
402
+
403
+ | Mode | Behavior |
404
+ |------|----------|
405
+ | `deny` | All commands blocked (default) |
406
+ | `allowlist` | Only approved patterns run; unknown commands are asked or denied |
407
+ | `full` | All commands allowed (use with caution) |
408
+
409
+ **Ask modes** (for `allowlist`):
410
+ - `on-miss` — ask the user via chat when a command isn't in the allowlist (recommended)
411
+ - `always` — ask for every command
412
+ - `off` — silently deny unknown commands
413
+
414
+ ```bash
415
+ flowly setup # Configure via wizard
416
+ flowly approvals status # View current config
417
+ flowly approvals list # View allowlist
418
+ ```
419
+
420
+ ### Device Pairing
421
+
422
+ Channels use a pairing system to authorize users:
423
+
424
+ ```bash
425
+ flowly pairing list # Pending requests
426
+ flowly pairing approve telegram CODE # Approve
427
+ flowly pairing revoke telegram USER # Revoke
428
+ flowly pairing allowed telegram # List allowed
429
+ ```
430
+
431
+ ## Background Service
432
+
433
+ Run Flowly as a persistent service — survives terminal close and auto-starts on boot:
434
+
435
+ ```bash
436
+ flowly service install --start # Install and start
437
+ flowly service status # Health check
438
+ flowly service logs -f # Follow logs
439
+ flowly service restart # Restart
440
+ flowly service stop # Stop
441
+ flowly service uninstall # Remove
442
+ ```
443
+
444
+ | Platform | Backend |
445
+ |----------|---------|
446
+ | macOS | launchd (LaunchAgents) |
447
+ | Linux | systemd (user service) |
448
+ | Windows | Task Scheduler |
449
+
450
+ ## Personas
451
+
452
+ Switch how Flowly talks without changing functionality:
453
+
454
+ ```bash
455
+ flowly persona list # See all
456
+ flowly persona set jarvis # Switch persona
457
+ flowly service restart # Apply
458
+ ```
459
+
460
+ | Persona | Style |
461
+ |---------|-------|
462
+ | `default` | Helpful and friendly |
463
+ | `jarvis` | J.A.R.V.I.S. — British AI, dry wit |
464
+ | `friday` | F.R.I.D.A.Y. — warm, professional |
465
+ | `pirate` | "Aye aye, Captain!" |
466
+ | `samurai` | Brief and wise |
467
+ | `casual` | Your best buddy |
468
+ | `professor` | Step-by-step explanations |
469
+ | `butler` | Distinguished, ultra-polite |
470
+
471
+ Create your own: drop a `.md` file in `~/.flowly/workspace/personas/`.
472
+
473
+ ## Voice Calls
474
+
475
+ Flowly can answer and make phone calls with real-time speech:
476
+
477
+ ```bash
478
+ flowly setup # Configure Twilio + STT/TTS
479
+ flowly gateway # Start with voice enabled
480
+ ```
481
+
482
+ **Supported providers:**
483
+ - **STT:** Groq Whisper, Deepgram, OpenAI, ElevenLabs
484
+ - **TTS:** ElevenLabs, Deepgram, OpenAI
485
+ - **Telephony:** Twilio
486
+
487
+ ## CLI Reference
488
+
489
+ ```
490
+ Setup & Config
491
+ flowly onboard Initialize config & workspace
492
+ flowly setup Interactive setup wizard
493
+ flowly setup agents Configure multi-agent (add agents, teams)
494
+ flowly status Overall system status
495
+
496
+ Agent
497
+ flowly agent -m "..." Send a single message
498
+ flowly agent Interactive chat mode
499
+ flowly gateway Start gateway (all channels)
500
+ flowly gateway --persona jarvis Start with a persona
501
+
502
+ Service
503
+ flowly service install --start Install and start background service
504
+ flowly service status Health check
505
+ flowly service logs -f Follow logs
506
+ flowly service restart Restart service
507
+ flowly service stop / uninstall Stop or remove
508
+
509
+ Channels
510
+ flowly channels login Link WhatsApp (QR code)
511
+ flowly channels status Channel connection status
512
+
513
+ Personas
514
+ flowly persona list List all personas
515
+ flowly persona set <name> Switch active persona
516
+ flowly persona show <name> View persona details
517
+
518
+ Skills
519
+ flowly skills list List installed skills
520
+ flowly skills search <query> Search skill hub
521
+ flowly skills install <name> Install a skill
522
+ flowly skills remove <name> Remove a skill
523
+
524
+ Scheduling
525
+ flowly cron list List scheduled jobs
526
+ flowly cron add Add a new job
527
+ flowly cron remove <id> Remove a job
528
+ flowly cron run <id> Manually run a job
529
+
530
+ Security
531
+ flowly approvals status Exec sandbox config
532
+ flowly approvals list View allowlist
533
+ flowly approvals add <pattern> Add allowlist pattern
534
+ flowly approvals remove <id> Remove allowlist entry
535
+ flowly pairing list Pending pairing requests
536
+ flowly pairing approve <ch> <code> Approve user
537
+ flowly pairing revoke <ch> <user> Revoke access
538
+ ```
539
+
540
+ ## Configuration
541
+
542
+ All config lives in `~/.flowly/config.json` (camelCase keys):
543
+
544
+ ```json
545
+ {
546
+ "providers": {
547
+ "openrouter": { "apiKey": "sk-or-v1-..." },
548
+ "xai": { "apiKey": "xai-..." },
549
+ "groq": { "apiKey": "gsk_..." }
550
+ },
551
+ "agents": {
552
+ "defaults": {
553
+ "model": "anthropic/claude-sonnet-4-5",
554
+ "maxTokens": 16384,
555
+ "temperature": 0.7,
556
+ "persona": "default"
557
+ },
558
+ "agents": {
559
+ "coder": { "provider": "anthropic", "model": "sonnet" },
560
+ "reviewer": { "provider": "openai", "model": "gpt-5.3-codex" }
561
+ },
562
+ "teams": {
563
+ "dev": { "agents": ["coder", "reviewer"], "leaderAgent": "coder" }
564
+ }
565
+ },
566
+ "channels": {
567
+ "telegram": { "enabled": true, "token": "...", "dmPolicy": "pairing" },
568
+ "discord": { "enabled": true, "token": "..." },
569
+ "slack": { "enabled": true, "botToken": "xoxb-...", "appToken": "xapp-..." },
570
+ "whatsapp": { "enabled": true }
571
+ },
572
+ "tools": {
573
+ "web": { "search": { "braveApiKey": "..." } },
574
+ "exec": {
575
+ "enabled": true,
576
+ "security": "allowlist",
577
+ "ask": "on-miss"
578
+ },
579
+ "mcpServers": {
580
+ "filesystem": {
581
+ "command": "npx",
582
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
583
+ }
584
+ }
585
+ },
586
+ "integrations": {
587
+ "trello": { "apiKey": "...", "token": "..." },
588
+ "x": {
589
+ "bearerToken": "...",
590
+ "apiKey": "...", "apiSecret": "...",
591
+ "accessToken": "...", "accessTokenSecret": "..."
592
+ },
593
+ "voice": { "enabled": true, "twilioAccountSid": "...", "twilioAuthToken": "..." }
594
+ },
595
+ "gateway": {
596
+ "host": "0.0.0.0",
597
+ "port": 18790
598
+ }
599
+ }
600
+ ```
601
+
602
+ ## Project Structure
603
+
604
+ ```
605
+ flowly/
606
+ ├── agent/ # Core agent loop, context, memory
607
+ │ └── tools/ # Built-in tools (shell, web, file, cron, delegate, ...)
608
+ ├── multiagent/ # Multi-agent orchestration (router, invoker, orchestrator) → [docs](flowly_code/multiagent/README.md)
609
+ ├── channels/ # Chat platform adapters (Telegram, Discord, ...)
610
+ ├── providers/ # LLM provider abstraction (LiteLLM)
611
+ ├── cli/ # CLI commands and setup wizard
612
+ ├── config/ # Configuration schema and loader
613
+ ├── cron/ # Task scheduling service
614
+ ├── session/ # Conversation session management
615
+ ├── bus/ # Event bus for message routing
616
+ ├── heartbeat/ # Periodic wake-up service
617
+ └── utils/ # Cross-platform utilities
618
+ ```
619
+
620
+ ## Requirements
621
+
622
+ | | Minimum |
623
+ |---|---|
624
+ | **Python** | ≥ 3.11 |
625
+ | **Node.js** | ≥ 18 (only for WhatsApp bridge) |
626
+ | **OS** | macOS, Linux, or Windows |
627
+
628
+ ## Desktop App
629
+
630
+ [Flowly Desktop](https://github.com/hakansoren/flowly-desktop) — Electron app with guided setup, one-click install, and visual management.
631
+
632
+ ## Contributing
633
+
634
+ Contributions are welcome! Flowly is designed to be readable and extensible:
635
+
636
+ - **Add a tool:** Create a class extending `Tool` in `flowly/agent/tools/`, register it in `loop.py`
637
+ - **Add a channel:** Implement `BaseChannel` in `flowly/channels/`
638
+ - **Add a provider:** Add detection logic in `flowly/providers/litellm_provider.py`
639
+ - **Add a skill:** Drop a `SKILL.md` in a new folder under `~/.flowly/workspace/skills/`
640
+
641
+ Please open an issue first for large changes.
642
+
643
+ ---
644
+
645
+ ## Changelog
646
+
647
+ <details>
648
+ <summary><strong>2026-02-18</strong> — MCP support, progress streaming</summary>
649
+
650
+ - MCP (Model Context Protocol) tool server support — connect stdio or HTTP MCP servers, tools auto-discovered and registered
651
+ - Progress streaming — real-time tool execution hints (`↳ web_search("query")`) in CLI and gateway channels
652
+ - Multi-agent orchestrator documentation (`multiagent/README.md`)
653
+
654
+ </details>
655
+
656
+ <details>
657
+ <summary><strong>2026-02-11</strong> — Multi-agent, X API, command execution (v1.0.0)</summary>
658
+
659
+ - Multi-agent delegation: send tasks to Claude Code, Codex, Gemini CLI, OpenCode, or Droid via `@mention` or `delegate_to` tool
660
+ - Fire-and-forget execution — agents run in background, results delivered asynchronously
661
+ - Interactive agent setup wizard: `flowly setup agents`
662
+ - X (Twitter) API integration (post, search, timeline, profiles)
663
+ - xAI/Grok as LiteLLM provider
664
+ - Command execution setup wizard
665
+ - Cron job results injected into user session
666
+ - License changed to Apache 2.0
667
+
668
+ </details>
669
+
670
+ <details>
671
+ <summary><strong>2026-02-10</strong> — Discord & Slack channels, setup wizard</summary>
672
+
673
+ - Discord and Slack channel implementations
674
+ - Interactive CLI setup wizard (`flowly setup`)
675
+ - Multi-channel manager support
676
+
677
+ </details>
678
+
679
+ <details>
680
+ <summary><strong>2026-02-09</strong> — Service mode, personas, screenshot delegation</summary>
681
+
682
+ - Background service mode (launchd/systemd/schtasks)
683
+ - 8 built-in personas (Jarvis, Friday, Pirate, etc.)
684
+ - Electron-delegated screenshot system
685
+ - Voice call improvements
686
+
687
+ </details>
688
+
689
+ <details>
690
+ <summary><strong>2026-02-06</strong> — Integrated voice system, new tools</summary>
691
+
692
+ - Twilio voice bridge with real-time audio streaming
693
+ - ElevenLabs, Deepgram, Groq Whisper STT/TTS providers
694
+ - Agentic voice call state machine
695
+ - System monitoring, Docker, Trello integration tools
696
+ - Cross-platform support (Windows/macOS/Linux)
697
+
698
+ </details>
699
+
700
+ <details>
701
+ <summary><strong>2026-02-04</strong> — Secure execution, pairing system</summary>
702
+
703
+ - Secure command execution sandbox
704
+ - Device pairing system
705
+ - Interactive setup CLI wizard
706
+
707
+ </details>
708
+
709
+ <details>
710
+ <summary><strong>2026-02-03</strong> — Initial release</summary>
711
+
712
+ - Core agent loop with LiteLLM provider
713
+ - Telegram and WhatsApp channels
714
+ - Cron scheduling, context compaction
715
+ - Groq Whisper voice transcription
716
+ - Flowly Hub skill management
717
+
718
+ </details>
719
+
720
+ ---
721
+
722
+ <p align="center">
723
+ <sub>Apache License 2.0 · Copyright 2025-2026 Nocetic Limited</sub>
724
+ </p>