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.
Files changed (69) hide show
  1. channels_cleaner-1.0.0/.gitignore +27 -0
  2. channels_cleaner-1.0.0/LICENSE +21 -0
  3. channels_cleaner-1.0.0/PKG-INFO +240 -0
  4. channels_cleaner-1.0.0/README.md +226 -0
  5. channels_cleaner-1.0.0/pyproject.toml +73 -0
  6. channels_cleaner-1.0.0/src/channels_cleaner/__init__.py +3 -0
  7. channels_cleaner-1.0.0/src/channels_cleaner/__main__.py +3 -0
  8. channels_cleaner-1.0.0/src/channels_cleaner/api/__init__.py +1 -0
  9. channels_cleaner-1.0.0/src/channels_cleaner/api/routes.py +261 -0
  10. channels_cleaner-1.0.0/src/channels_cleaner/api/schemas.py +98 -0
  11. channels_cleaner-1.0.0/src/channels_cleaner/api/sse.py +42 -0
  12. channels_cleaner-1.0.0/src/channels_cleaner/app.py +86 -0
  13. channels_cleaner-1.0.0/src/channels_cleaner/browser.py +45 -0
  14. channels_cleaner-1.0.0/src/channels_cleaner/cli.py +131 -0
  15. channels_cleaner-1.0.0/src/channels_cleaner/config.py +87 -0
  16. channels_cleaner-1.0.0/src/channels_cleaner/context.py +92 -0
  17. channels_cleaner-1.0.0/src/channels_cleaner/db.py +634 -0
  18. channels_cleaner-1.0.0/src/channels_cleaner/events.py +43 -0
  19. channels_cleaner-1.0.0/src/channels_cleaner/pulse.py +66 -0
  20. channels_cleaner-1.0.0/src/channels_cleaner/services/__init__.py +1 -0
  21. channels_cleaner-1.0.0/src/channels_cleaner/services/apply.py +229 -0
  22. channels_cleaner-1.0.0/src/channels_cleaner/services/auth.py +222 -0
  23. channels_cleaner-1.0.0/src/channels_cleaner/services/channels.py +122 -0
  24. channels_cleaner-1.0.0/src/channels_cleaner/services/stats.py +103 -0
  25. channels_cleaner-1.0.0/src/channels_cleaner/services/sync.py +105 -0
  26. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/AppIcon-B455SEv2.js +3 -0
  27. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/ApplyView-Ef5_TVTy.js +1 -0
  28. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/DeckView--M2Hj6PH.js +1 -0
  29. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/DeckView-C-aUEL5r.css +1 -0
  30. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/LoginView-BOBiQotC.js +8 -0
  31. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/LoginView-DGG29VRK.css +1 -0
  32. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/ResultsView-C7_kuPDv.js +1 -0
  33. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/ReviewView-D_FJ0qn5.js +1 -0
  34. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/apply-BofR4vEF.js +1 -0
  35. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/index-3qPgnHck.css +1 -0
  36. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/index-Bn4Kxt2R.js +3 -0
  37. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-cyrillic-wght-normal-D73BlboJ.woff2 +0 -0
  38. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-greek-wght-normal-Bw9x6K1M.woff2 +0 -0
  39. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-latin-ext-wght-normal-DBQx-q_a.woff2 +0 -0
  40. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-latin-wght-normal-B9CIFXIH.woff2 +0 -0
  41. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jetbrains-mono-vietnamese-wght-normal-Bt-aOZkq.woff2 +0 -0
  42. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jost-cyrillic-wght-normal-CjwCQKo9.woff2 +0 -0
  43. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jost-latin-ext-wght-normal-BDUtSsKd.woff2 +0 -0
  44. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/jost-latin-wght-normal-ObQm3Zd1.woff2 +0 -0
  45. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-cyrillic-ext-wght-normal-DOFToQv1.woff2 +0 -0
  46. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-cyrillic-wght-normal-DayYxulF.woff2 +0 -0
  47. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-latin-ext-wght-normal-QAhDxQuo.woff2 +0 -0
  48. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-latin-wght-normal-Dun_Rd-l.woff2 +0 -0
  49. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-math-wght-normal-Bl4ZGkZl.woff2 +0 -0
  50. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-symbols-wght-normal-DxQzqQfC.woff2 +0 -0
  51. channels_cleaner-1.0.0/src/channels_cleaner/static/assets/onest-vietnamese-wght-normal-BBxOatbv.woff2 +0 -0
  52. channels_cleaner-1.0.0/src/channels_cleaner/static/favicon.svg +1 -0
  53. channels_cleaner-1.0.0/src/channels_cleaner/static/index.html +18 -0
  54. channels_cleaner-1.0.0/src/channels_cleaner/telegram/__init__.py +1 -0
  55. channels_cleaner-1.0.0/src/channels_cleaner/telegram/device_profiles.json +326 -0
  56. channels_cleaner-1.0.0/src/channels_cleaner/telegram/device_profiles.py +61 -0
  57. channels_cleaner-1.0.0/src/channels_cleaner/telegram/gateway.py +71 -0
  58. channels_cleaner-1.0.0/src/channels_cleaner/telegram/kurigram_gateway.py +403 -0
  59. channels_cleaner-1.0.0/src/channels_cleaner/telegram/mock_gateway.py +382 -0
  60. channels_cleaner-1.0.0/src/channels_cleaner/telegram/types.py +84 -0
  61. channels_cleaner-1.0.0/tests/__init__.py +0 -0
  62. channels_cleaner-1.0.0/tests/conftest.py +79 -0
  63. channels_cleaner-1.0.0/tests/test_auth.py +65 -0
  64. channels_cleaner-1.0.0/tests/test_browser.py +48 -0
  65. channels_cleaner-1.0.0/tests/test_cli.py +96 -0
  66. channels_cleaner-1.0.0/tests/test_config.py +32 -0
  67. channels_cleaner-1.0.0/tests/test_deck.py +157 -0
  68. channels_cleaner-1.0.0/tests/test_device_profiles.py +29 -0
  69. 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
+ [![CI](https://github.com/asteroid-den/channels-cleaner-userbot/actions/workflows/ci.yml/badge.svg)](https://github.com/asteroid-den/channels-cleaner-userbot/actions/workflows/ci.yml)
18
+ [![PyPI](https://img.shields.io/pypi/v/channels-cleaner)](https://pypi.org/project/channels-cleaner/)
19
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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
+ ![Swiping through channels in mock mode](docs/media/demo.gif)
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
+ | ![The deck in the light theme](docs/media/deck-light.png) | ![Magnified history over the progress bar](docs/media/loupe.png) |
54
+ | **Review** | **Applying** |
55
+ | ![Review screen grouping the queued actions](docs/media/review.png) | ![Actions being applied one by one](docs/media/apply.png) |
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
+ [![CI](https://github.com/asteroid-den/channels-cleaner-userbot/actions/workflows/ci.yml/badge.svg)](https://github.com/asteroid-den/channels-cleaner-userbot/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/channels-cleaner)](https://pypi.org/project/channels-cleaner/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](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
+ ![Swiping through channels in mock mode](docs/media/demo.gif)
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
+ | ![The deck in the light theme](docs/media/deck-light.png) | ![Magnified history over the progress bar](docs/media/loupe.png) |
40
+ | **Review** | **Applying** |
41
+ | ![Review screen grouping the queued actions](docs/media/review.png) | ![Actions being applied one by one](docs/media/apply.png) |
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,3 @@
1
+ """Channels Cleaner — Tinder-like cleanup of Telegram channel subscriptions."""
2
+
3
+ __version__ = "1.0.0"
@@ -0,0 +1,3 @@
1
+ from channels_cleaner.cli import main
2
+
3
+ main()
@@ -0,0 +1 @@
1
+ """HTTP API (REST + Server-Sent Events)."""