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.
- flowly_code/__init__.py +30 -0
- flowly_code/__main__.py +8 -0
- flowly_code/activity/__init__.py +1 -0
- flowly_code/activity/bus.py +91 -0
- flowly_code/activity/events.py +40 -0
- flowly_code/agent/__init__.py +8 -0
- flowly_code/agent/context.py +485 -0
- flowly_code/agent/loop.py +1349 -0
- flowly_code/agent/memory.py +109 -0
- flowly_code/agent/skills.py +259 -0
- flowly_code/agent/subagent.py +249 -0
- flowly_code/agent/tools/__init__.py +6 -0
- flowly_code/agent/tools/base.py +55 -0
- flowly_code/agent/tools/delegate.py +194 -0
- flowly_code/agent/tools/dispatch.py +840 -0
- flowly_code/agent/tools/docker.py +609 -0
- flowly_code/agent/tools/filesystem.py +280 -0
- flowly_code/agent/tools/mcp.py +85 -0
- flowly_code/agent/tools/message.py +235 -0
- flowly_code/agent/tools/registry.py +257 -0
- flowly_code/agent/tools/screenshot.py +444 -0
- flowly_code/agent/tools/shell.py +166 -0
- flowly_code/agent/tools/spawn.py +65 -0
- flowly_code/agent/tools/system.py +917 -0
- flowly_code/agent/tools/trello.py +420 -0
- flowly_code/agent/tools/web.py +139 -0
- flowly_code/agent/tools/x.py +399 -0
- flowly_code/bus/__init__.py +6 -0
- flowly_code/bus/events.py +37 -0
- flowly_code/bus/queue.py +81 -0
- flowly_code/channels/__init__.py +6 -0
- flowly_code/channels/base.py +121 -0
- flowly_code/channels/manager.py +135 -0
- flowly_code/channels/telegram.py +1132 -0
- flowly_code/cli/__init__.py +1 -0
- flowly_code/cli/commands.py +1831 -0
- flowly_code/cli/setup.py +1356 -0
- flowly_code/compaction/__init__.py +39 -0
- flowly_code/compaction/estimator.py +88 -0
- flowly_code/compaction/pruning.py +223 -0
- flowly_code/compaction/service.py +297 -0
- flowly_code/compaction/summarizer.py +384 -0
- flowly_code/compaction/types.py +71 -0
- flowly_code/config/__init__.py +6 -0
- flowly_code/config/loader.py +102 -0
- flowly_code/config/schema.py +324 -0
- flowly_code/exec/__init__.py +39 -0
- flowly_code/exec/approvals.py +288 -0
- flowly_code/exec/executor.py +184 -0
- flowly_code/exec/safety.py +247 -0
- flowly_code/exec/types.py +88 -0
- flowly_code/gateway/__init__.py +5 -0
- flowly_code/gateway/server.py +103 -0
- flowly_code/heartbeat/__init__.py +5 -0
- flowly_code/heartbeat/service.py +130 -0
- flowly_code/multiagent/README.md +248 -0
- flowly_code/multiagent/__init__.py +1 -0
- flowly_code/multiagent/invoke.py +210 -0
- flowly_code/multiagent/orchestrator.py +156 -0
- flowly_code/multiagent/router.py +156 -0
- flowly_code/multiagent/setup.py +171 -0
- flowly_code/pairing/__init__.py +21 -0
- flowly_code/pairing/store.py +343 -0
- flowly_code/providers/__init__.py +6 -0
- flowly_code/providers/base.py +69 -0
- flowly_code/providers/litellm_provider.py +178 -0
- flowly_code/providers/transcription.py +64 -0
- flowly_code/session/__init__.py +5 -0
- flowly_code/session/manager.py +249 -0
- flowly_code/skills/README.md +24 -0
- flowly_code/skills/compact/SKILL.md +27 -0
- flowly_code/skills/github/SKILL.md +48 -0
- flowly_code/skills/skill-creator/SKILL.md +371 -0
- flowly_code/skills/summarize/SKILL.md +67 -0
- flowly_code/skills/tmux/SKILL.md +121 -0
- flowly_code/skills/tmux/scripts/find-sessions.sh +112 -0
- flowly_code/skills/tmux/scripts/wait-for-text.sh +83 -0
- flowly_code/skills/weather/SKILL.md +49 -0
- flowly_code/utils/__init__.py +5 -0
- flowly_code/utils/helpers.py +91 -0
- flowly_code-1.0.0.dist-info/METADATA +724 -0
- flowly_code-1.0.0.dist-info/RECORD +86 -0
- flowly_code-1.0.0.dist-info/WHEEL +4 -0
- flowly_code-1.0.0.dist-info/entry_points.txt +2 -0
- flowly_code-1.0.0.dist-info/licenses/LICENSE +191 -0
- 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>
|