channels-cleaner 1.0.0__tar.gz
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.
- channels_cleaner-1.0.0/.gitignore +27 -0
- channels_cleaner-1.0.0/LICENSE +21 -0
- channels_cleaner-1.0.0/PKG-INFO +240 -0
- channels_cleaner-1.0.0/README.md +226 -0
- channels_cleaner-1.0.0/pyproject.toml +73 -0
- channels_cleaner-1.0.0/src/channels_cleaner/__init__.py +3 -0
- channels_cleaner-1.0.0/src/channels_cleaner/__main__.py +3 -0
- channels_cleaner-1.0.0/src/channels_cleaner/api/__init__.py +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/api/routes.py +261 -0
- channels_cleaner-1.0.0/src/channels_cleaner/api/schemas.py +98 -0
- channels_cleaner-1.0.0/src/channels_cleaner/api/sse.py +42 -0
- channels_cleaner-1.0.0/src/channels_cleaner/app.py +86 -0
- channels_cleaner-1.0.0/src/channels_cleaner/browser.py +45 -0
- channels_cleaner-1.0.0/src/channels_cleaner/cli.py +131 -0
- channels_cleaner-1.0.0/src/channels_cleaner/config.py +87 -0
- channels_cleaner-1.0.0/src/channels_cleaner/context.py +92 -0
- channels_cleaner-1.0.0/src/channels_cleaner/db.py +634 -0
- channels_cleaner-1.0.0/src/channels_cleaner/events.py +43 -0
- channels_cleaner-1.0.0/src/channels_cleaner/pulse.py +66 -0
- channels_cleaner-1.0.0/src/channels_cleaner/services/__init__.py +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/services/apply.py +229 -0
- channels_cleaner-1.0.0/src/channels_cleaner/services/auth.py +222 -0
- channels_cleaner-1.0.0/src/channels_cleaner/services/channels.py +122 -0
- channels_cleaner-1.0.0/src/channels_cleaner/services/stats.py +103 -0
- channels_cleaner-1.0.0/src/channels_cleaner/services/sync.py +105 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/AppIcon-B455SEv2.js +3 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/ApplyView-Ef5_TVTy.js +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/DeckView--M2Hj6PH.js +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/DeckView-C-aUEL5r.css +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/LoginView-BOBiQotC.js +8 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/LoginView-DGG29VRK.css +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/ResultsView-C7_kuPDv.js +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/ReviewView-D_FJ0qn5.js +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/apply-BofR4vEF.js +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/index-3qPgnHck.css +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/index-Bn4Kxt2R.js +3 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-cyrillic-wght-normal-D73BlboJ.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-greek-wght-normal-Bw9x6K1M.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-latin-ext-wght-normal-DBQx-q_a.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-latin-wght-normal-B9CIFXIH.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-vietnamese-wght-normal-Bt-aOZkq.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jost-cyrillic-wght-normal-CjwCQKo9.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jost-latin-ext-wght-normal-BDUtSsKd.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jost-latin-wght-normal-ObQm3Zd1.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-cyrillic-ext-wght-normal-DOFToQv1.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-cyrillic-wght-normal-DayYxulF.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-latin-ext-wght-normal-QAhDxQuo.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-latin-wght-normal-Dun_Rd-l.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-math-wght-normal-Bl4ZGkZl.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-symbols-wght-normal-DxQzqQfC.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-vietnamese-wght-normal-BBxOatbv.woff2 +0 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/favicon.svg +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/static/index.html +18 -0
- channels_cleaner-1.0.0/src/channels_cleaner/telegram/__init__.py +1 -0
- channels_cleaner-1.0.0/src/channels_cleaner/telegram/device_profiles.json +326 -0
- channels_cleaner-1.0.0/src/channels_cleaner/telegram/device_profiles.py +61 -0
- channels_cleaner-1.0.0/src/channels_cleaner/telegram/gateway.py +71 -0
- channels_cleaner-1.0.0/src/channels_cleaner/telegram/kurigram_gateway.py +403 -0
- channels_cleaner-1.0.0/src/channels_cleaner/telegram/mock_gateway.py +382 -0
- channels_cleaner-1.0.0/src/channels_cleaner/telegram/types.py +84 -0
- channels_cleaner-1.0.0/tests/__init__.py +0 -0
- channels_cleaner-1.0.0/tests/conftest.py +79 -0
- channels_cleaner-1.0.0/tests/test_auth.py +65 -0
- channels_cleaner-1.0.0/tests/test_browser.py +48 -0
- channels_cleaner-1.0.0/tests/test_cli.py +96 -0
- channels_cleaner-1.0.0/tests/test_config.py +32 -0
- channels_cleaner-1.0.0/tests/test_deck.py +157 -0
- channels_cleaner-1.0.0/tests/test_device_profiles.py +29 -0
- channels_cleaner-1.0.0/tests/test_pulse.py +46 -0
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
.venv/
|
|
5
|
+
.mypy_cache/
|
|
6
|
+
.ruff_cache/
|
|
7
|
+
.pytest_cache/
|
|
8
|
+
dist/
|
|
9
|
+
build/
|
|
10
|
+
*.egg-info/
|
|
11
|
+
|
|
12
|
+
# App data (sessions, DB, media cache) — never commit
|
|
13
|
+
data/
|
|
14
|
+
*.session
|
|
15
|
+
*.session-journal
|
|
16
|
+
.env
|
|
17
|
+
|
|
18
|
+
# Built frontend
|
|
19
|
+
src/channels_cleaner/static/
|
|
20
|
+
|
|
21
|
+
# Editors / OS
|
|
22
|
+
.idea/
|
|
23
|
+
.vscode/
|
|
24
|
+
.DS_Store
|
|
25
|
+
|
|
26
|
+
# Local tooling
|
|
27
|
+
.claude/
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Denis Serebriakov
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: channels-cleaner
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Tinder-like cleanup of your Telegram channel subscriptions, running locally
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Python: >=3.12
|
|
8
|
+
Requires-Dist: aiosqlite>=0.21
|
|
9
|
+
Requires-Dist: fastapi>=0.115
|
|
10
|
+
Requires-Dist: kurigram[fast]>=2.2.27
|
|
11
|
+
Requires-Dist: pydantic-settings>=2.6
|
|
12
|
+
Requires-Dist: uvicorn[standard]>=0.32
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
|
|
15
|
+
# Channels Cleaner
|
|
16
|
+
|
|
17
|
+
[](https://github.com/asteroid-den/channels-cleaner-userbot/actions/workflows/ci.yml)
|
|
18
|
+
[](https://pypi.org/project/channels-cleaner/)
|
|
19
|
+
[](LICENSE)
|
|
20
|
+
|
|
21
|
+
Go through every Telegram channel you're subscribed to, one card at a time, and get rid of the
|
|
22
|
+
ones you stopped reading years ago. Swipe left to leave, right to keep, or mute and archive.
|
|
23
|
+
Nothing changes in Telegram until you've reviewed the whole batch.
|
|
24
|
+
|
|
25
|
+
It runs on your own computer: a small Python server (a [Kurigram](https://github.com/KurimuzonAkuma/pyrogram)
|
|
26
|
+
userbot + FastAPI) and a web UI that opens in your browser. No hosted service, no accounts.
|
|
27
|
+
|
|
28
|
+

|
|
29
|
+
|
|
30
|
+
## What it does
|
|
31
|
+
|
|
32
|
+
- **One card per channel, with the numbers that matter**: posts per week (or how long it's been
|
|
33
|
+
silent), a 26-week activity chart, subscribers, unread count and a preview of the last post.
|
|
34
|
+
The card takes its colour from the channel's avatar.
|
|
35
|
+
- **Five verdicts**: unsubscribe, keep, mute, archive or "later" (back of the deck). Swipe the
|
|
36
|
+
card, click either side of it or use the keyboard.
|
|
37
|
+
- **Two orders**: dead channels first (never posted, then longest silence) or most unread first,
|
|
38
|
+
each reversible.
|
|
39
|
+
- **The progress bar is your history.** Every decision lands in it in order, coloured by
|
|
40
|
+
verdict. Hover it to see a magnified strip of avatars, click to go back to any decision and
|
|
41
|
+
change it, or step through them with <kbd>Ctrl</kbd>+<kbd>←</kbd>/<kbd>→</kbd>.
|
|
42
|
+
- **Nothing happens until you confirm.** Unsubscribe, mute and archive are queued. The review
|
|
43
|
+
screen groups them, flags private channels you can't rejoin without an invite, then applies
|
|
44
|
+
them one by one with pauses, handling Telegram's flood waits.
|
|
45
|
+
- **Changed your mind later?** Turn an applied mute or archive into "keep" and the next run
|
|
46
|
+
unmutes or unarchives the channel.
|
|
47
|
+
- **Results and export**: what's left of your subscriptions by last post, plus a CSV/JSON list
|
|
48
|
+
of what you left, with `t.me` links for the public ones.
|
|
49
|
+
- QR or phone login with two-step verification, English and Russian, dark and light themes.
|
|
50
|
+
|
|
51
|
+
| Deck (light theme) | History loupe |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
|  |  |
|
|
54
|
+
| **Review** | **Applying** |
|
|
55
|
+
|  |  |
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
You need Python 3.12+ and either [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/).
|
|
60
|
+
The package includes the built UI, so no Node.js is required.
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
uvx channels-cleaner
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
or install it once and run it whenever you like:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
pipx install channels-cleaner
|
|
70
|
+
channels-cleaner
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
A browser tab opens at <http://127.0.0.1:8765>. On your phone, open Telegram →
|
|
74
|
+
**Settings → Devices → Link Desktop Device** and scan the QR code. You can also log in with a
|
|
75
|
+
phone number and code; a two-step verification password is asked for when it's set.
|
|
76
|
+
|
|
77
|
+
### Try it without a Telegram account
|
|
78
|
+
|
|
79
|
+
Mock mode replaces Telegram with 120 generated channels:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
uvx channels-cleaner --mock
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The QR code "scans" itself after a few seconds. The phone code is `12345`; with `CC_MOCK_2FA=1`
|
|
86
|
+
the 2FA password is `mock`. The screenshots above are from mock mode.
|
|
87
|
+
|
|
88
|
+
### Docker
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
docker run --rm -p 127.0.0.1:8765:8765 -v channels-cleaner:/data \
|
|
92
|
+
ghcr.io/asteroid-den/channels-cleaner-userbot:latest
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Then open <http://127.0.0.1:8765>. Or from a checkout: `docker compose up -d`. Keep the
|
|
96
|
+
`127.0.0.1:` part of the port mapping: the UI has no password, and whoever can open it can act
|
|
97
|
+
on your Telegram account.
|
|
98
|
+
|
|
99
|
+
### From source
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
git clone https://github.com/asteroid-den/channels-cleaner-userbot.git
|
|
103
|
+
cd channels-cleaner-userbot
|
|
104
|
+
npm --prefix frontend ci && npm --prefix frontend run build # Node.js 22.18+
|
|
105
|
+
uv run channels-cleaner
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Keyboard
|
|
109
|
+
|
|
110
|
+
| Key | Action |
|
|
111
|
+
| --- | --- |
|
|
112
|
+
| <kbd>←</kbd> / <kbd>→</kbd> | Unsubscribe / keep |
|
|
113
|
+
| <kbd>↓</kbd> | Later: move to the back of the deck |
|
|
114
|
+
| <kbd>M</kbd> / <kbd>A</kbd> | Mute / archive |
|
|
115
|
+
| <kbd>Ctrl</kbd>+<kbd>Z</kbd> or <kbd>Backspace</kbd> | Undo the last decision |
|
|
116
|
+
| <kbd>Ctrl</kbd>+<kbd>←</kbd> / <kbd>→</kbd> | Step back / forward through decisions you've made |
|
|
117
|
+
| <kbd>Enter</kbd> | Go to the review |
|
|
118
|
+
| <kbd>Ctrl</kbd>+<kbd>Enter</kbd> | Apply (on the review screen) |
|
|
119
|
+
| <kbd>Esc</kbd> | Back to the deck |
|
|
120
|
+
|
|
121
|
+
Letter keys work on any keyboard layout. On macOS, <kbd>Cmd</kbd> works in place of
|
|
122
|
+
<kbd>Ctrl</kbd>.
|
|
123
|
+
|
|
124
|
+
## Privacy and safety
|
|
125
|
+
|
|
126
|
+
**Read this before logging in with your real account.**
|
|
127
|
+
|
|
128
|
+
- **The session file is your Telegram account.** Anyone who copies it can read your messages
|
|
129
|
+
and act as you, without your password or 2FA. It lives in the data directory below, which
|
|
130
|
+
the app keeps readable only by your user (on Linux and macOS). Don't sync it to the cloud,
|
|
131
|
+
don't share it.
|
|
132
|
+
- **Everything stays on your machine.** The server listens on `127.0.0.1` only, talks to
|
|
133
|
+
Telegram directly and nowhere else. There is no telemetry.
|
|
134
|
+
- **The UI has no password**, because it's meant for one person on their own computer. Don't
|
|
135
|
+
expose it to a network (`--host 0.0.0.0`) you don't fully control.
|
|
136
|
+
- **Log out and delete local data** in the account menu ends the session on Telegram's side
|
|
137
|
+
and wipes everything stored for that account. Ending the session from Telegram
|
|
138
|
+
(**Settings → Devices**) also works; delete the data directory afterwards.
|
|
139
|
+
|
|
140
|
+
### Where the data lives
|
|
141
|
+
|
|
142
|
+
| How you run it | Location |
|
|
143
|
+
| --- | --- |
|
|
144
|
+
| `uvx` / `pipx` on Linux | `~/.local/share/channels-cleaner` (or `$XDG_DATA_HOME`) |
|
|
145
|
+
| `uvx` / `pipx` on macOS | `~/Library/Application Support/channels-cleaner` |
|
|
146
|
+
| `uvx` / `pipx` on Windows | `%APPDATA%\channels-cleaner` |
|
|
147
|
+
| From source | `./data` in the checkout |
|
|
148
|
+
| Docker | the `/data` volume |
|
|
149
|
+
|
|
150
|
+
The startup message prints the exact path. Inside:
|
|
151
|
+
|
|
152
|
+
- `sessions/account.session`: the Telegram session.
|
|
153
|
+
- `sessions/account.device.json`: the device profile this session presents to Telegram.
|
|
154
|
+
- `cleaner.sqlite3`: the channel cache, your decisions and stats.
|
|
155
|
+
- `media/`: cached avatars and post thumbnails.
|
|
156
|
+
|
|
157
|
+
### About the API id and the device profile
|
|
158
|
+
|
|
159
|
+
Telegram identifies third-party clients by an `api_id`. Out of the box this app uses the public
|
|
160
|
+
`api_id` of Telegram Desktop and, on first login, picks a plausible Telegram Desktop device
|
|
161
|
+
profile (OS, app version, language) from
|
|
162
|
+
[`device_profiles.json`](src/channels_cleaner/telegram/device_profiles.json). The profile is
|
|
163
|
+
stored with the session and never changes after that, so in **Settings → Devices** you'll see
|
|
164
|
+
one ordinary desktop session rather than a new device on every start.
|
|
165
|
+
|
|
166
|
+
To be clear about what that means: the app presents itself as Telegram Desktop. Using an
|
|
167
|
+
unofficial client is at your own risk under
|
|
168
|
+
[Telegram's Terms of Service](https://core.telegram.org/api/terms), and Telegram can limit
|
|
169
|
+
accounts it considers abusive. For a cleaner setup, register your own app at
|
|
170
|
+
<https://my.telegram.org/apps> and set `CC_API_ID` and `CC_API_HASH`.
|
|
171
|
+
|
|
172
|
+
### Pace
|
|
173
|
+
|
|
174
|
+
Reading is cheap: channel details and the last 100 post dates are fetched lazily, one card at a
|
|
175
|
+
time, and cached for 72 hours. Actions run one after another with a random 1.5–3 s pause. If
|
|
176
|
+
Telegram replies with a flood wait, the job sleeps for the time it was told to (the UI shows a
|
|
177
|
+
countdown) and carries on. You can stop the job at any point; whatever wasn't applied stays
|
|
178
|
+
queued. Channels you own or administer are never shown.
|
|
179
|
+
|
|
180
|
+
## Configuration
|
|
181
|
+
|
|
182
|
+
Everything is optional. Use environment variables or a `.env` file in the working directory
|
|
183
|
+
(see [`.env.example`](.env.example)).
|
|
184
|
+
|
|
185
|
+
| CLI flag | Env var | Default | |
|
|
186
|
+
| --- | --- | --- | --- |
|
|
187
|
+
| `--host` | `CC_HOST` | `127.0.0.1` | Address to listen on |
|
|
188
|
+
| `--port` | `CC_PORT` | `8765` | Port |
|
|
189
|
+
| `--no-browser` | `CC_NO_BROWSER=1` | off | Don't open a browser tab |
|
|
190
|
+
| `--mock` | `CC_MOCK=1` | off | Fake Telegram backend |
|
|
191
|
+
| | `CC_MOCK_CHANNELS` | `120` | Number of generated channels |
|
|
192
|
+
| | `CC_MOCK_2FA=1` | off | Ask for a 2FA password in mock mode |
|
|
193
|
+
| | `CC_DATA_DIR` | see above | Sessions, database, media cache |
|
|
194
|
+
| | `CC_API_ID`, `CC_API_HASH` | Telegram Desktop | Your own Telegram API credentials |
|
|
195
|
+
| | `CC_APPLY_DELAY_MIN`, `CC_APPLY_DELAY_MAX` | `1.5`, `3.0` | Pause between actions, seconds |
|
|
196
|
+
| | `CC_FULL_INFO_TTL_HOURS` | `72` | How long channel details stay cached |
|
|
197
|
+
| `-v` | | off | Debug logging |
|
|
198
|
+
|
|
199
|
+
## Development
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
uv sync
|
|
203
|
+
npm --prefix frontend ci
|
|
204
|
+
|
|
205
|
+
uv run channels-cleaner --mock --dev # API only, on :8765
|
|
206
|
+
npm --prefix frontend run dev # UI with hot reload on :5173, proxies /api
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
Checks, the same as CI:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest
|
|
213
|
+
cd frontend && npm run lint && npm run format:check && npm run test && npm run build
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
```
|
|
217
|
+
src/channels_cleaner/
|
|
218
|
+
telegram/ gateway protocol; Kurigram and mock implementations; device profiles
|
|
219
|
+
services/ auth state machine, sync, lazy channel info + activity, apply job, stats
|
|
220
|
+
api/ FastAPI routes: REST + Server-Sent Events
|
|
221
|
+
db.py SQLite schema, migrations and queries
|
|
222
|
+
frontend/src/ Vue 3 + Vite + TypeScript, Pinia, vue-i18n, Tailwind
|
|
223
|
+
stores/ auth, deck (queue, history, rewind), apply, ui
|
|
224
|
+
views/ Login, Deck, Review, Apply, Results
|
|
225
|
+
components/ swipe deck, channel card, progress bar + loupe, summary pill…
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Releasing
|
|
229
|
+
|
|
230
|
+
Push a `v*` tag matching `__version__` in
|
|
231
|
+
[`src/channels_cleaner/__init__.py`](src/channels_cleaner/__init__.py). The
|
|
232
|
+
[release workflow](.github/workflows/release.yml) builds the wheel with the UI, publishes it to
|
|
233
|
+
PyPI through trusted publishing and pushes a multi-arch image to GHCR. One-time setup: on
|
|
234
|
+
pypi.org, add a pending trusted publisher for project `channels-cleaner` with workflow
|
|
235
|
+
`release.yml` and environment `pypi`, and create an environment named `pypi` in the
|
|
236
|
+
repository settings.
|
|
237
|
+
|
|
238
|
+
## License
|
|
239
|
+
|
|
240
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
# Channels Cleaner
|
|
2
|
+
|
|
3
|
+
[](https://github.com/asteroid-den/channels-cleaner-userbot/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/channels-cleaner/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
Go through every Telegram channel you're subscribed to, one card at a time, and get rid of the
|
|
8
|
+
ones you stopped reading years ago. Swipe left to leave, right to keep, or mute and archive.
|
|
9
|
+
Nothing changes in Telegram until you've reviewed the whole batch.
|
|
10
|
+
|
|
11
|
+
It runs on your own computer: a small Python server (a [Kurigram](https://github.com/KurimuzonAkuma/pyrogram)
|
|
12
|
+
userbot + FastAPI) and a web UI that opens in your browser. No hosted service, no accounts.
|
|
13
|
+
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
## What it does
|
|
17
|
+
|
|
18
|
+
- **One card per channel, with the numbers that matter**: posts per week (or how long it's been
|
|
19
|
+
silent), a 26-week activity chart, subscribers, unread count and a preview of the last post.
|
|
20
|
+
The card takes its colour from the channel's avatar.
|
|
21
|
+
- **Five verdicts**: unsubscribe, keep, mute, archive or "later" (back of the deck). Swipe the
|
|
22
|
+
card, click either side of it or use the keyboard.
|
|
23
|
+
- **Two orders**: dead channels first (never posted, then longest silence) or most unread first,
|
|
24
|
+
each reversible.
|
|
25
|
+
- **The progress bar is your history.** Every decision lands in it in order, coloured by
|
|
26
|
+
verdict. Hover it to see a magnified strip of avatars, click to go back to any decision and
|
|
27
|
+
change it, or step through them with <kbd>Ctrl</kbd>+<kbd>←</kbd>/<kbd>→</kbd>.
|
|
28
|
+
- **Nothing happens until you confirm.** Unsubscribe, mute and archive are queued. The review
|
|
29
|
+
screen groups them, flags private channels you can't rejoin without an invite, then applies
|
|
30
|
+
them one by one with pauses, handling Telegram's flood waits.
|
|
31
|
+
- **Changed your mind later?** Turn an applied mute or archive into "keep" and the next run
|
|
32
|
+
unmutes or unarchives the channel.
|
|
33
|
+
- **Results and export**: what's left of your subscriptions by last post, plus a CSV/JSON list
|
|
34
|
+
of what you left, with `t.me` links for the public ones.
|
|
35
|
+
- QR or phone login with two-step verification, English and Russian, dark and light themes.
|
|
36
|
+
|
|
37
|
+
| Deck (light theme) | History loupe |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
|  |  |
|
|
40
|
+
| **Review** | **Applying** |
|
|
41
|
+
|  |  |
|
|
42
|
+
|
|
43
|
+
## Quick start
|
|
44
|
+
|
|
45
|
+
You need Python 3.12+ and either [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/).
|
|
46
|
+
The package includes the built UI, so no Node.js is required.
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
uvx channels-cleaner
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
or install it once and run it whenever you like:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pipx install channels-cleaner
|
|
56
|
+
channels-cleaner
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
A browser tab opens at <http://127.0.0.1:8765>. On your phone, open Telegram →
|
|
60
|
+
**Settings → Devices → Link Desktop Device** and scan the QR code. You can also log in with a
|
|
61
|
+
phone number and code; a two-step verification password is asked for when it's set.
|
|
62
|
+
|
|
63
|
+
### Try it without a Telegram account
|
|
64
|
+
|
|
65
|
+
Mock mode replaces Telegram with 120 generated channels:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
uvx channels-cleaner --mock
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The QR code "scans" itself after a few seconds. The phone code is `12345`; with `CC_MOCK_2FA=1`
|
|
72
|
+
the 2FA password is `mock`. The screenshots above are from mock mode.
|
|
73
|
+
|
|
74
|
+
### Docker
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
docker run --rm -p 127.0.0.1:8765:8765 -v channels-cleaner:/data \
|
|
78
|
+
ghcr.io/asteroid-den/channels-cleaner-userbot:latest
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Then open <http://127.0.0.1:8765>. Or from a checkout: `docker compose up -d`. Keep the
|
|
82
|
+
`127.0.0.1:` part of the port mapping: the UI has no password, and whoever can open it can act
|
|
83
|
+
on your Telegram account.
|
|
84
|
+
|
|
85
|
+
### From source
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
git clone https://github.com/asteroid-den/channels-cleaner-userbot.git
|
|
89
|
+
cd channels-cleaner-userbot
|
|
90
|
+
npm --prefix frontend ci && npm --prefix frontend run build # Node.js 22.18+
|
|
91
|
+
uv run channels-cleaner
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Keyboard
|
|
95
|
+
|
|
96
|
+
| Key | Action |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| <kbd>←</kbd> / <kbd>→</kbd> | Unsubscribe / keep |
|
|
99
|
+
| <kbd>↓</kbd> | Later: move to the back of the deck |
|
|
100
|
+
| <kbd>M</kbd> / <kbd>A</kbd> | Mute / archive |
|
|
101
|
+
| <kbd>Ctrl</kbd>+<kbd>Z</kbd> or <kbd>Backspace</kbd> | Undo the last decision |
|
|
102
|
+
| <kbd>Ctrl</kbd>+<kbd>←</kbd> / <kbd>→</kbd> | Step back / forward through decisions you've made |
|
|
103
|
+
| <kbd>Enter</kbd> | Go to the review |
|
|
104
|
+
| <kbd>Ctrl</kbd>+<kbd>Enter</kbd> | Apply (on the review screen) |
|
|
105
|
+
| <kbd>Esc</kbd> | Back to the deck |
|
|
106
|
+
|
|
107
|
+
Letter keys work on any keyboard layout. On macOS, <kbd>Cmd</kbd> works in place of
|
|
108
|
+
<kbd>Ctrl</kbd>.
|
|
109
|
+
|
|
110
|
+
## Privacy and safety
|
|
111
|
+
|
|
112
|
+
**Read this before logging in with your real account.**
|
|
113
|
+
|
|
114
|
+
- **The session file is your Telegram account.** Anyone who copies it can read your messages
|
|
115
|
+
and act as you, without your password or 2FA. It lives in the data directory below, which
|
|
116
|
+
the app keeps readable only by your user (on Linux and macOS). Don't sync it to the cloud,
|
|
117
|
+
don't share it.
|
|
118
|
+
- **Everything stays on your machine.** The server listens on `127.0.0.1` only, talks to
|
|
119
|
+
Telegram directly and nowhere else. There is no telemetry.
|
|
120
|
+
- **The UI has no password**, because it's meant for one person on their own computer. Don't
|
|
121
|
+
expose it to a network (`--host 0.0.0.0`) you don't fully control.
|
|
122
|
+
- **Log out and delete local data** in the account menu ends the session on Telegram's side
|
|
123
|
+
and wipes everything stored for that account. Ending the session from Telegram
|
|
124
|
+
(**Settings → Devices**) also works; delete the data directory afterwards.
|
|
125
|
+
|
|
126
|
+
### Where the data lives
|
|
127
|
+
|
|
128
|
+
| How you run it | Location |
|
|
129
|
+
| --- | --- |
|
|
130
|
+
| `uvx` / `pipx` on Linux | `~/.local/share/channels-cleaner` (or `$XDG_DATA_HOME`) |
|
|
131
|
+
| `uvx` / `pipx` on macOS | `~/Library/Application Support/channels-cleaner` |
|
|
132
|
+
| `uvx` / `pipx` on Windows | `%APPDATA%\channels-cleaner` |
|
|
133
|
+
| From source | `./data` in the checkout |
|
|
134
|
+
| Docker | the `/data` volume |
|
|
135
|
+
|
|
136
|
+
The startup message prints the exact path. Inside:
|
|
137
|
+
|
|
138
|
+
- `sessions/account.session`: the Telegram session.
|
|
139
|
+
- `sessions/account.device.json`: the device profile this session presents to Telegram.
|
|
140
|
+
- `cleaner.sqlite3`: the channel cache, your decisions and stats.
|
|
141
|
+
- `media/`: cached avatars and post thumbnails.
|
|
142
|
+
|
|
143
|
+
### About the API id and the device profile
|
|
144
|
+
|
|
145
|
+
Telegram identifies third-party clients by an `api_id`. Out of the box this app uses the public
|
|
146
|
+
`api_id` of Telegram Desktop and, on first login, picks a plausible Telegram Desktop device
|
|
147
|
+
profile (OS, app version, language) from
|
|
148
|
+
[`device_profiles.json`](src/channels_cleaner/telegram/device_profiles.json). The profile is
|
|
149
|
+
stored with the session and never changes after that, so in **Settings → Devices** you'll see
|
|
150
|
+
one ordinary desktop session rather than a new device on every start.
|
|
151
|
+
|
|
152
|
+
To be clear about what that means: the app presents itself as Telegram Desktop. Using an
|
|
153
|
+
unofficial client is at your own risk under
|
|
154
|
+
[Telegram's Terms of Service](https://core.telegram.org/api/terms), and Telegram can limit
|
|
155
|
+
accounts it considers abusive. For a cleaner setup, register your own app at
|
|
156
|
+
<https://my.telegram.org/apps> and set `CC_API_ID` and `CC_API_HASH`.
|
|
157
|
+
|
|
158
|
+
### Pace
|
|
159
|
+
|
|
160
|
+
Reading is cheap: channel details and the last 100 post dates are fetched lazily, one card at a
|
|
161
|
+
time, and cached for 72 hours. Actions run one after another with a random 1.5–3 s pause. If
|
|
162
|
+
Telegram replies with a flood wait, the job sleeps for the time it was told to (the UI shows a
|
|
163
|
+
countdown) and carries on. You can stop the job at any point; whatever wasn't applied stays
|
|
164
|
+
queued. Channels you own or administer are never shown.
|
|
165
|
+
|
|
166
|
+
## Configuration
|
|
167
|
+
|
|
168
|
+
Everything is optional. Use environment variables or a `.env` file in the working directory
|
|
169
|
+
(see [`.env.example`](.env.example)).
|
|
170
|
+
|
|
171
|
+
| CLI flag | Env var | Default | |
|
|
172
|
+
| --- | --- | --- | --- |
|
|
173
|
+
| `--host` | `CC_HOST` | `127.0.0.1` | Address to listen on |
|
|
174
|
+
| `--port` | `CC_PORT` | `8765` | Port |
|
|
175
|
+
| `--no-browser` | `CC_NO_BROWSER=1` | off | Don't open a browser tab |
|
|
176
|
+
| `--mock` | `CC_MOCK=1` | off | Fake Telegram backend |
|
|
177
|
+
| | `CC_MOCK_CHANNELS` | `120` | Number of generated channels |
|
|
178
|
+
| | `CC_MOCK_2FA=1` | off | Ask for a 2FA password in mock mode |
|
|
179
|
+
| | `CC_DATA_DIR` | see above | Sessions, database, media cache |
|
|
180
|
+
| | `CC_API_ID`, `CC_API_HASH` | Telegram Desktop | Your own Telegram API credentials |
|
|
181
|
+
| | `CC_APPLY_DELAY_MIN`, `CC_APPLY_DELAY_MAX` | `1.5`, `3.0` | Pause between actions, seconds |
|
|
182
|
+
| | `CC_FULL_INFO_TTL_HOURS` | `72` | How long channel details stay cached |
|
|
183
|
+
| `-v` | | off | Debug logging |
|
|
184
|
+
|
|
185
|
+
## Development
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
uv sync
|
|
189
|
+
npm --prefix frontend ci
|
|
190
|
+
|
|
191
|
+
uv run channels-cleaner --mock --dev # API only, on :8765
|
|
192
|
+
npm --prefix frontend run dev # UI with hot reload on :5173, proxies /api
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Checks, the same as CI:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest
|
|
199
|
+
cd frontend && npm run lint && npm run format:check && npm run test && npm run build
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
```
|
|
203
|
+
src/channels_cleaner/
|
|
204
|
+
telegram/ gateway protocol; Kurigram and mock implementations; device profiles
|
|
205
|
+
services/ auth state machine, sync, lazy channel info + activity, apply job, stats
|
|
206
|
+
api/ FastAPI routes: REST + Server-Sent Events
|
|
207
|
+
db.py SQLite schema, migrations and queries
|
|
208
|
+
frontend/src/ Vue 3 + Vite + TypeScript, Pinia, vue-i18n, Tailwind
|
|
209
|
+
stores/ auth, deck (queue, history, rewind), apply, ui
|
|
210
|
+
views/ Login, Deck, Review, Apply, Results
|
|
211
|
+
components/ swipe deck, channel card, progress bar + loupe, summary pill…
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Releasing
|
|
215
|
+
|
|
216
|
+
Push a `v*` tag matching `__version__` in
|
|
217
|
+
[`src/channels_cleaner/__init__.py`](src/channels_cleaner/__init__.py). The
|
|
218
|
+
[release workflow](.github/workflows/release.yml) builds the wheel with the UI, publishes it to
|
|
219
|
+
PyPI through trusted publishing and pushes a multi-arch image to GHCR. One-time setup: on
|
|
220
|
+
pypi.org, add a pending trusted publisher for project `channels-cleaner` with workflow
|
|
221
|
+
`release.yml` and environment `pypi`, and create an environment named `pypi` in the
|
|
222
|
+
repository settings.
|
|
223
|
+
|
|
224
|
+
## License
|
|
225
|
+
|
|
226
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "channels-cleaner"
|
|
3
|
+
dynamic = ["version"]
|
|
4
|
+
description = "Tinder-like cleanup of your Telegram channel subscriptions, running locally"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
requires-python = ">=3.12"
|
|
8
|
+
dependencies = [
|
|
9
|
+
"aiosqlite>=0.21",
|
|
10
|
+
"fastapi>=0.115",
|
|
11
|
+
# "fast" = kuricrypt: prebuilt wheels for every platform (tgcrypto needs a C compiler)
|
|
12
|
+
"kurigram[fast]>=2.2.27",
|
|
13
|
+
"pydantic-settings>=2.6",
|
|
14
|
+
"uvicorn[standard]>=0.32",
|
|
15
|
+
]
|
|
16
|
+
|
|
17
|
+
[project.scripts]
|
|
18
|
+
channels-cleaner = "channels_cleaner.cli:main"
|
|
19
|
+
|
|
20
|
+
[dependency-groups]
|
|
21
|
+
dev = [
|
|
22
|
+
"httpx>=0.28",
|
|
23
|
+
"mypy>=1.13",
|
|
24
|
+
"pytest>=8.3",
|
|
25
|
+
"pytest-asyncio>=0.24",
|
|
26
|
+
"ruff>=0.8",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[build-system]
|
|
30
|
+
requires = ["hatchling"]
|
|
31
|
+
build-backend = "hatchling.build"
|
|
32
|
+
|
|
33
|
+
[tool.hatch.version]
|
|
34
|
+
path = "src/channels_cleaner/__init__.py"
|
|
35
|
+
|
|
36
|
+
# The built UI (src/channels_cleaner/static) is gitignored, so it is listed as an artifact:
|
|
37
|
+
# build the frontend first (`npm --prefix frontend run build`), then `uv build`.
|
|
38
|
+
[tool.hatch.build.targets.sdist]
|
|
39
|
+
only-include = ["src/channels_cleaner", "tests", "README.md", "LICENSE", "pyproject.toml"]
|
|
40
|
+
artifacts = ["src/channels_cleaner/static/**"]
|
|
41
|
+
|
|
42
|
+
[tool.hatch.build.targets.wheel]
|
|
43
|
+
packages = ["src/channels_cleaner"]
|
|
44
|
+
artifacts = ["src/channels_cleaner/static/**"]
|
|
45
|
+
|
|
46
|
+
[tool.ruff]
|
|
47
|
+
line-length = 100
|
|
48
|
+
target-version = "py312"
|
|
49
|
+
src = ["src", "tests"]
|
|
50
|
+
|
|
51
|
+
[tool.ruff.lint]
|
|
52
|
+
select = ["E", "W", "F", "I", "B", "UP", "SIM", "ASYNC", "RUF", "PT", "C4", "RET"]
|
|
53
|
+
ignore = ["RUF001", "RUF002", "RUF003"]
|
|
54
|
+
|
|
55
|
+
[tool.ruff.lint.per-file-ignores]
|
|
56
|
+
"src/channels_cleaner/api/*.py" = ["B008"]
|
|
57
|
+
"tests/*.py" = ["ASYNC109", "ASYNC110"]
|
|
58
|
+
|
|
59
|
+
[tool.mypy]
|
|
60
|
+
python_version = "3.12"
|
|
61
|
+
strict = true
|
|
62
|
+
files = ["src", "tests"]
|
|
63
|
+
plugins = ["pydantic.mypy"]
|
|
64
|
+
|
|
65
|
+
[[tool.mypy.overrides]]
|
|
66
|
+
module = ["pyrogram", "pyrogram.*"]
|
|
67
|
+
ignore_missing_imports = true
|
|
68
|
+
follow_imports = "skip"
|
|
69
|
+
|
|
70
|
+
[tool.pytest.ini_options]
|
|
71
|
+
asyncio_mode = "auto"
|
|
72
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
73
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""HTTP API (REST + Server-Sent Events)."""
|