feat: incremental Telegram media backup

Single-file tool that downloads photos and documents from a Telegram
chat and resumes where it left off.

Durability:
- process oldest-to-newest and persist last_id after every message, so
  an interrupted run resumes instead of rescanning
- write state.json via temp file + rename; a torn write would otherwise
  leave unparseable JSON and block the next run
- download to a .part file and rename on success, so a killed run cannot
  leave a truncated file that the exists() check treats as complete
- retry transient errors with exponential backoff alongside the existing
  FloodWait handling, and skip permanently failed files rather than
  stalling the run

Usability:
- share one session across all archive dirs, so a login covers every
  chat instead of one per directory; migrate an existing per-archive
  session in place rather than forcing re-authentication
- create the config template before argument parsing, since --target was
  required but unknowable before the API keys were set
- add --list-chats to print dialog IDs and usernames
- convert numeric targets to int; Telethon resolves a numeric string as
  a username and never consults the entity cache

Hardening:
- strip path components from sender-controlled filenames
- create config and session files 0600 in a 0700 directory

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

5 files changed, 799 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..f59898a
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,10 @@
+# Telegram session files are account credentials. Never commit them.
+*.session
+*.session-journal
+
+# Default archive dir, plus its media and resume state
+tg_archive/
+state.json
+
+__pycache__/
+*.pyc
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..551fc5f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Single-file Python script (`tg_backup.py`, ~115 lines) that incrementally downloads media (photos + documents) from a Telegram chat/group via Telethon. No package, no tests, no build step. Keep it single-file unless there is a real reason not to.
+
+Dependency: `telethon` only.
+
+## Running
+
+```bash
+./tg_backup.py --list-chats --archive-dir ./tg_archive   # find IDs
+./tg_backup.py --target @somegroup --archive-dir ./tg_archive
+./tg_backup.py --target=-1001234567890 --archive-dir ./tg_archive
+```
+
+Negative chat IDs need `--target=<id>`; argparse reads a bare `-100...` as a flag. `--list-chats` prints ID, type, `@username` (or `-` when the chat has no public handle), and display name.
+
+`parse_target` converts digit-only targets to `int` before `get_entity`. This is load-bearing: Telethon resolves a numeric *string* as a username and fails, while an `int` hits the session's entity cache. Usernames, `me`, and t.me links pass through as strings.
+
+First run without a config writes a template to `~/.config/telegram_backup/config.json` and exits; the user fills in `api_id`/`api_hash` from my.telegram.org. Telethon then prompts interactively for phone/code on first auth, so the script cannot be run unattended the first time.
+
+## Design invariants
+
+Three things are load-bearing and easy to break:
+
+1. **`reverse=True` on `iter_messages`** (`tg_backup.py:75`). Processing must be oldest-to-newest. `state['last_id']` is a high-water mark used as `min_id` on resume; iterating newest-first would make it skip unfetched history permanently.
+2. **State saved after every message**, not at the end, via temp-file + `os.replace`. Cheap insurance against interruption; do not "optimize" into a batched write without keeping resume correctness, and keep the write atomic. A truncated `state.json` makes the next run unstartable.
+3. **Two-level retry handling.** The inner `download_with_retry` retries a single file up to `MAX_RETRIES`: FloodWait sleeps the server-requested interval, other exceptions (network drops, expired file references, disk errors) get exponential backoff so one flaky socket can't kill an overnight run. The outer `while True` in `run_backup` catches FloodWait on history fetching, saves state, sleeps, and restarts the iterator from the saved id. A permanently failed download still advances state on purpose, so one broken file can't wedge the backup forever.
+4. **Media downloads to `{name}.part`, renamed on success.** The dedup check is `filepath.exists()`, so a truncated file at the final path would be skipped forever as if complete. The `.part` file is unlinked on failure and on interrupt, leaving the message to be retried on the next run.
+
+Resume/dedup is also file-based: media is named `{message.id}_{sanitized_name}` (see `safe_filename`, which strips sender-controlled path components) and an existing path is skipped, so state loss degrades to a slow rescan rather than re-downloading everything.
+
+## Checks
+
+`python3 tg_backup.py --self-check` exercises `safe_filename` path-traversal handling and `save_state`/`load_state` round-tripping. No network, no login. It does import telethon, so it needs the dep installed.
+
+## Layout
+
+`--archive-dir` holds media files and `state.json`, and is created if missing (`parents=True`). It is per-chat: one dir per backed-up chat.
+
+Auth lives in `~/.config/telegram_backup/` (mode 0700): `config.json` with the api_id/api_hash, and `session.session`, a single Telethon session **shared by every archive dir**, so one login covers all chats. `migrate_session` relocates a pre-existing `<archive_dir>/session.session` to the shared path on first run rather than forcing a re-login; it is a no-op once the shared session exists. It uses `shutil.move`, not `os.replace`, because the two paths can be on different filesystems.
+
+The session file is account credentials: anyone holding it can read the account's Telegram. Keep it 0600 and out of git.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..9efa6fb
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,338 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Moe Ghoul>, 1 April 1989
+  Moe Ghoul, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..32a7fe2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+# tg_backup
+
+Incremental media backup for Telegram chats. Downloads photos and documents from a chat, remembers where it stopped, and picks up from there on the next run.
+
+Single Python file, one dependency ([Telethon](https://docs.telethon.dev/)).
+
+## Install
+
+```bash
+pip install telethon
+cp tg_backup.py ~/bin/ && chmod +x ~/bin/tg_backup.py
+```
+
+## Setup
+
+Run it once with no arguments to create the config:
+
+```bash
+tg_backup.py
+```
+
+It writes `~/.config/telegram_backup/config.json` and exits. Fill in the two values from [my.telegram.org](https://my.telegram.org) (API development tools):
+
+```json
+{
+    "api_id": 12345,
+    "api_hash": "<your 32-character hash>"
+}
+```
+
+`api_id` is an integer, `api_hash` a 32-character hex string.
+
+Nothing else from that page is needed. FCM credentials and MTProto server addresses are for full client implementations.
+
+The first real run prompts for your phone number and login code. That session is saved and shared by every subsequent run, so you log in once.
+
+## Usage
+
+List your chats to find a target:
+
+```bash
+tg_backup.py --list-chats
+```
+
+```
+             ID  TYPE      USERNAME              NAME
+ -1001234567890  group     @examplegroup         Example Group
+      123456789  user      @examplecontact       Example Contact
+      987654321  user      -                     Contact Without Handle
+```
+
+Back one up:
+
+```bash
+tg_backup.py --target=@examplegroup --archive-dir ~/backups/examplegroup
+tg_backup.py --target=-1001234567890 --archive-dir ~/backups/examplegroup
+```
+
+Numeric IDs are more durable than usernames, which their owners can change. Chats showing `-` have no public handle and can only be addressed by ID.
+
+`--target` also accepts `me` (Saved Messages), t.me links, and invite links for groups you have already joined.
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--target` | required | Chat to back up: `@username`, numeric ID, t.me link, or `me` |
+| `--archive-dir` | `./tg_archive` | Where media and resume state are written; created if missing |
+| `--list-chats` | | Print your dialogs with IDs and usernames, then exit |
+| `--self-check` | | Run internal assertions and exit. No network, no login |
+
+Use one archive directory per chat. Prefer absolute paths: the default is relative to the current directory, so running from elsewhere silently starts a second archive.
+
+### Negative IDs need `=`
+
+```bash
+tg_backup.py --target=-1001234567890     # correct
+tg_backup.py --target -1001234567890     # error: expected one argument
+```
+
+Without `=`, argparse reads the leading `-` as the start of another flag.
+
+## How it works
+
+Messages are processed oldest to newest, and the last message ID seen is written to `state.json` in the archive directory after every message. An interrupted run resumes from there instead of rescanning the whole chat.
+
+Media is saved as `{message_id}_{original_name}`. Downloads land in a temporary `.part` file and are renamed only on success, so a killed run never leaves a truncated file that a later run would mistake for a complete one. Files that already exist are skipped, so even a lost `state.json` degrades to a slow rescan rather than re-downloading everything.
+
+Rate limits are handled at two levels: Telegram's requested wait is honoured for both individual downloads and history fetches, and other errors (dropped connections, expired file references) are retried with exponential backoff. A download that fails permanently is logged and skipped rather than stalling the run forever.
+
+Only media is saved. Message text and captions are not.
+
+## Files
+
+| Path | Contents |
+|---|---|
+| `~/.config/telegram_backup/config.json` | API credentials |
+| `~/.config/telegram_backup/session.session` | Login session, shared across all archive directories |
+| `<archive-dir>/state.json` | Resume position for that chat |
+| `<archive-dir>/*` | Downloaded media |
+
+The session file is account credentials: anyone holding it can read your Telegram. It is created mode `0600` inside a `0700` directory. Keep it out of version control and off shared storage.
+
+## License
+
+Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+
+Released under the GNU General Public License version 2. See [LICENSE](LICENSE) for the full text.
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.
diff --git a/tg_backup.py b/tg_backup.py
new file mode 100644
index 0000000..e038b92
--- /dev/null
+++ b/tg_backup.py
@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+#
+# tg_backup.py - incremental Telegram media backup
+#
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+
+import argparse
+import asyncio
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from telethon import TelegramClient
+from telethon.errors import FloodWaitError
+from telethon.tl.types import MessageMediaPhoto, MessageMediaDocument
+
+CONFIG_DIR = Path.home() / ".config" / "telegram_backup"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+# Shared across every archive dir: one login covers all chats. Telethon appends
+# ".session", so the file on disk is session.session.
+SESSION_FILE = CONFIG_DIR / "session"
+MAX_RETRIES = 5
+
+def bootstrap_config():
+    # Called before argparse: --target is required, but a user with no config
+    # has nothing useful to pass yet. Without this, a bare run exits on the
+    # missing argument and never creates the template.
+    if not CONFIG_FILE.exists():
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        CONFIG_DIR.chmod(0o700)  # holds API keys and the shared session
+        template = {"api_id": "YOUR_API_ID", "api_hash": "YOUR_API_HASH"}
+        CONFIG_FILE.write_text(json.dumps(template, indent=4))
+        CONFIG_FILE.chmod(0o600)
+        sys.exit(f"Config created at {CONFIG_FILE}. Fill in API keys and run again.")
+
+def load_config():
+    bootstrap_config()
+
+    with open(CONFIG_FILE, 'r') as f:
+        config = json.load(f)
+
+    api_id, api_hash = config.get('api_id'), config.get('api_hash')
+    if not api_id or not api_hash or 'YOUR_' in (str(api_id) + str(api_hash)):
+        sys.exit("Error: Invalid or missing API keys in config.")
+    return config
+
+def load_state(archive_dir):
+    state_file = archive_dir / "state.json"
+    if state_file.exists():
+        with open(state_file, 'r') as f:
+            return json.load(f)
+    return {'last_id': 0}
+
+def save_state(archive_dir, state):
+    # Written after every message, so an interrupted write is a matter of time.
+    # Write to a temp file and rename: readers see the old state or the new one,
+    # never a truncated file that would make the next run unstartable.
+    state_file = archive_dir / "state.json"
+    tmp_file = state_file.with_name(state_file.name + ".tmp")
+    with open(tmp_file, 'w') as f:
+        json.dump(state, f, indent=4)
+    os.replace(tmp_file, state_file)
+
+def safe_filename(message_id, original_name, ext):
+    # original_name comes from the sender. Strip path components so a name like
+    # "../../.ssh/authorized_keys" resolves to a plain file inside archive_dir.
+    name = Path(original_name or f"media{ext}").name
+    if name in ('', '.', '..'):
+        name = f"media{ext}"
+    return f"{message_id}_{name}"
+
+async def download_with_retry(client, message, filepath):
+    # Download to a .part file so an interrupted run never leaves a truncated
+    # file that the exists() check would mistake for a complete download.
+    partpath = filepath.with_name(filepath.name + ".part")
+    for attempt in range(MAX_RETRIES):
+        try:
+            await client.download_media(message, file=str(partpath))
+            os.replace(partpath, filepath)
+            return True
+        except FloodWaitError as e:
+            print(f"Rate limited on download. Waiting {e.seconds}s... (Attempt {attempt+1}/{MAX_RETRIES})")
+            await asyncio.sleep(e.seconds)
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            partpath.unlink(missing_ok=True)
+            raise
+        except Exception as e:
+            # Network drops, expired file references, disk errors. Backing off
+            # and retrying beats killing an overnight run on one bad socket.
+            delay = 2 ** attempt
+            print(f"Download error on {filepath.name}: {e}. "
+                  f"Retrying in {delay}s... (Attempt {attempt+1}/{MAX_RETRIES})")
+            partpath.unlink(missing_ok=True)
+            await asyncio.sleep(delay)
+    partpath.unlink(missing_ok=True)
+    print(f"Failed to download {filepath.name} after {MAX_RETRIES} retries.")
+    return False
+
+def migrate_session(archive_dir):
+    # Sessions used to live per-archive-dir, which forced a fresh login for every
+    # chat. Move an old one to the shared location instead of making the user
+    # re-authenticate. Only runs when there is no shared session yet.
+    shared = SESSION_FILE.with_suffix(".session")
+    old = archive_dir / "session.session"
+    if not shared.exists() and old.exists():
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(old), str(shared))  # may cross filesystems
+        shared.chmod(0o600)
+        print(f"Moved existing login from {old} to {shared}.")
+
+def parse_target(target):
+    # Telethon resolves a numeric *string* as a username and fails; only a real
+    # int hits the session's cached-entity lookup. --list-chats prints ints, so
+    # convert them back before handing off to get_entity().
+    t = target.strip()
+    if t.lstrip('-').isdigit():
+        return int(t)
+    return t
+
+def make_client(archive_dir):
+    # One session in CONFIG_DIR, shared by every archive dir: log in once, back
+    # up any number of chats.
+    config = load_config()
+    archive_dir.mkdir(parents=True, exist_ok=True)
+    migrate_session(archive_dir)
+    return TelegramClient(str(SESSION_FILE), config['api_id'], config['api_hash'])
+
+async def start_client(client):
+    # Telethon prompts for phone/code on first login. Without a TTY that
+    # surfaces as a bare EOFError traceback, which says nothing useful.
+    try:
+        await client.start()
+    except EOFError:
+        sys.exit("First login needs an interactive terminal (phone + code). "
+                 "Run this once by hand, then the saved session works unattended.")
+
+def entity_username(entity):
+    # Telethon exposes both a legacy .username and a newer .usernames list
+    # (multiple public handles). .username can be None while .usernames is set.
+    username = getattr(entity, 'username', None)
+    if username:
+        return username
+    for u in getattr(entity, 'usernames', None) or []:
+        name = getattr(u, 'username', None)
+        if name:
+            return name
+    return None
+
+async def list_chats(archive_dir):
+    client = make_client(archive_dir)
+    await start_client(client)
+    try:
+        print(f"{'ID':>15}  {'TYPE':<8}  {'USERNAME':<20}  NAME")
+        async for dialog in client.iter_dialogs():
+            kind = 'user' if dialog.is_user else 'group' if dialog.is_group else 'channel'
+            # Not every chat has one: private groups and users who never set a
+            # public handle resolve by numeric ID only.
+            username = entity_username(dialog.entity)
+            handle = f"@{username}" if username else "-"
+            print(f"{dialog.id:>15}  {kind:<8}  {handle:<20}  {dialog.name}")
+    finally:
+        await client.disconnect()
+    print("\nBack up with: --target=<ID>   (the = matters for negative IDs)")
+
+async def run_backup(target, archive_dir):
+    client = make_client(archive_dir)
+    await start_client(client)
+
+    try:
+        entity = await client.get_entity(parse_target(target))
+    except Exception as e:
+        sys.exit(f"Failed to resolve target '{target}': {e}\n"
+                 "Run --list-chats first: numeric IDs only resolve once the "
+                 "chat is in the session's entity cache.")
+
+    state = load_state(archive_dir)
+    last_id = state['last_id']
+    print(f"Resuming from message ID: {last_id}")
+    
+    # reverse=True ensures oldest-to-newest processing. 
+    # Critical for safe incremental state tracking.
+    while True:
+        try:
+            async for message in client.iter_messages(entity, min_id=last_id, reverse=True):
+                if isinstance(message.media, (MessageMediaPhoto, MessageMediaDocument)):
+                    ext = message.file.ext or '.jpg'
+                    filename = safe_filename(message.id, message.file.name, ext)
+                    filepath = archive_dir / filename
+                    
+                    if not filepath.exists():
+                        print(f"Downloading {filename}...")
+                        success = await download_with_retry(client, message, filepath)
+                        if not success:
+                            # If download permanently fails, we still advance state 
+                            # so we don't get stuck on a broken file forever.
+                            print("Skipping file due to max retries.")
+                    else:
+                        print(f"Skipping {filename} (exists).")
+                        
+                # Save state after every message to ensure progress is kept
+                state['last_id'] = message.id
+                save_state(archive_dir, state)
+            break # Loop completes successfully
+            
+        except FloodWaitError as e:
+            print(f"Rate limited on history fetch. Waiting {e.seconds}s...")
+            save_state(archive_dir, state) # Save before sleeping
+            await asyncio.sleep(e.seconds)
+            # Loop restarts, fetching from the last saved ID
+
+    print("Backup complete.")
+
+def main():
+    bootstrap_config()
+    parser = argparse.ArgumentParser(description="Incremental Telegram media backup.")
+    parser.add_argument("--target", help="Group username (@name), ID, or invite link.")
+    parser.add_argument("--archive-dir", type=Path, default=Path("./tg_archive"),
+                        help="Directory to store media and state.")
+    parser.add_argument("--list-chats", action="store_true",
+                        help="List your dialogs with their IDs and exit.")
+
+    args = parser.parse_args()
+    if args.list_chats:
+        asyncio.run(list_chats(args.archive_dir))
+    elif args.target:
+        asyncio.run(run_backup(args.target, args.archive_dir))
+    else:
+        parser.error("--target is required (or use --list-chats)")
+
+def _self_check():
+    """Run with --self-check. Guards the path-traversal and state-write logic."""
+    import tempfile
+    archive = Path(tempfile.mkdtemp()).resolve()
+
+    for hostile in ['../../.ssh/authorized_keys', '..', '.', '', None,
+                    '/etc/passwd', 'a/../../b', '....//x', 'ok.jpg']:
+        path = (archive / safe_filename(7, hostile, '.jpg')).resolve()
+        assert path.parent == archive, f"escaped archive dir: {hostile!r} -> {path}"
+    assert safe_filename(7, 'ok.jpg', '.jpg') == '7_ok.jpg'
+    assert safe_filename(7, None, '.jpg') == '7_media.jpg'
+
+    # Username extraction must survive both telethon shapes and neither.
+    class _E: pass
+    class _U:
+        def __init__(s, n): s.username = n
+    legacy = _E(); legacy.username = 'examplecontact'
+    assert entity_username(legacy) == 'examplecontact'
+    multi = _E(); multi.username = None; multi.usernames = [_U('newstyle')]
+    assert entity_username(multi) == 'newstyle'
+    assert entity_username(_E()) is None
+    none_set = _E(); none_set.username = None; none_set.usernames = []
+    assert entity_username(none_set) is None
+
+    # Numeric targets must reach get_entity() as ints or the cache is missed.
+    assert parse_target('123456789') == 123456789
+    assert parse_target('-1001234567890') == -1001234567890
+    assert parse_target(' 42 ') == 42
+    assert parse_target('@examplecontact') == '@examplecontact'
+    assert parse_target('me') == 'me'
+    assert parse_target('https://t.me/foo') == 'https://t.me/foo'
+
+    # State survives a rewrite and never leaves a stray temp file behind.
+    save_state(archive, {'last_id': 1})
+    save_state(archive, {'last_id': 42})
+    assert load_state(archive) == {'last_id': 42}
+    assert not list(archive.glob('*.tmp')), "temp state file left behind"
+    assert load_state(Path(tempfile.mkdtemp())) == {'last_id': 0}
+
+    print("self-check OK")
+
+if __name__ == "__main__":
+    if '--self-check' in sys.argv:
+        _self_check()
+    else:
+        main()
\ No newline at end of file