Threads Archiver

Warning

이 도구는 Threads 로그인 세션이 필요할 수 있습니다. 가능하면 평소 사용하는 개인 메인 계정 대신, 아카이빙 전용 Threads 계정을 새로 만들어 사용하는 것을 권장합니다. 장기 자동화, 반복 수집, 브라우저 프로필 보관을 고려하면 전용 계정 분리가 가장 안전합니다.

Caution

이 저장소와 스킬은 로컬 자동화 도구를 제공할 뿐이며, 실제 사용에 따른 책임은 사용자에게 있습니다. Threads를 포함한 각 플랫폼의 이용약관, 자동화 정책, 로그인 정책, 접근 제한 정책을 직접 확인한 뒤 사용해야 합니다. 계정 제한, 로그인 차단, 세션 만료, 수집 실패, 서비스 정책 위반 판단 등 사용 중 발생할 수 있는 문제는 사용 환경과 운용 방식에 따라 달라질 수 있으며, 이에 대한 최종 책임은 사용자 본인에게 있습니다. 특히 장기 자동화나 반복 수집을 운영할 경우에는 메인 계정보다 별도 아카이빙 전용 계정 사용을 권장합니다.

Threads 게시물과 self-reply 체인을 로컬 vault에 저장하는 저토큰 자동화 도구입니다.

상단 요약:

• CLI, GUI, Skill mode 3가지 방식으로 실행할 수 있습니다.
• 실제 수집과 저장은 Python, Playwright, JSONL ledger, 파일시스템으로 처리됩니다.
• 반복 수집 작업에 LLM 토큰을 거의 쓰지 않아서 자동화용 스킬로 적합합니다.

빠른 사용 흐름

처음 쓰는 경우에는 아래 순서대로 진행하면 됩니다.

1. 가능하면 아카이버 전용 Threads 계정을 새로 만듭니다.
2. Windows에서는 .\setup_threads_archiver_windows.bat 으로 환경을 준비합니다. macOS에서는 아래 CLI 예시를 참고하세요.
3. tools/threads-archiver.config.json 에 vault 경로를 설정합니다.
4. python .\tools\archive_threads.py login --profile-dir $HOME\.threads_profile 로 로그인 세션을 저장합니다.
5. 최근 글 기준으로 먼저 한 번 수집합니다.
6. 필요하면 이후에는 GUI 또는 주기 실행으로 운영합니다.

가장 간단한 첫 실행 예시:

.\setup_threads_archiver_windows.bat
python .\tools\archive_threads.py login --profile-dir $HOME\.threads_profile
python .\tools\archive_threads.py --account @username recent --days 7 --profile-dir $HOME\.threads_profile

macOS에서는 기본 Python에 tkinter가 없을 수 있으므로, Python 3.11/3.12 계열과 Playwright Chromium을 별도로 준비한 뒤 CLI부터 시작하는 편이 안전합니다.

추천 운영 방식

• 처음에는 recent 모드로 짧게 테스트합니다.
• 안정화되면 weekly 모드나 GUI 스케줄링으로 전환합니다.
• 로그인 세션과 브라우저 프로필은 개인 메인 계정보다 아카이버 전용 계정으로 분리하는 편이 안전합니다.
• 공개 저장소 그대로 사용할 때도 threads-archiver.config.json, 쿠키 파일, 브라우저 프로필은 Git에 넣지 않는 것을 권장합니다.

Archive Threads posts and self-reply chains into a local vault with minimal LLM involvement.

This project supports three operating modes:

• CLI for scripted or scheduled runs
• GUI for interactive desktop use on Windows
• Skill mode for agent workflows that call the same implementation through thin wrappers

It is designed to be a low-token automation skill. The actual work is done locally with Python, Playwright, JSONL ledgers, and filesystem writes, so agents can trigger it without spending meaningful prompt tokens on repeated collection work.

Why this repo exists

Threads posts are often published as multi-post self-reply chains. This tool is built to preserve:

• root posts
• the author's own continuation replies
• downloaded media
• incremental sync history in append-only ledgers
• readable markdown notes for local knowledge management

tools/ is the single source of truth for the implementation. The skill package under .agent/skills/threads-archiver/ delegates to the same tools/ scripts instead of maintaining a second implementation.

Features

• Batch archive recent or incremental profile activity
• Capture self-reply chains while ignoring unrelated reply trees
• Download images and videos locally
• Maintain append-only JSONL ledgers for runs and posts
• Rebuild notes and indexes from ledger data
• Run through CLI, GUI, or skill wrappers
• Use a dedicated archiver config without requiring full KM setup

Repository layout

• tools/: main implementation and utilities
• .agent/skills/threads-archiver/: skill wrapper, docs, and script bridges
• run_threads_gui.bat: Windows GUI launcher
• setup_threads_archiver_windows.bat: Windows setup helper

Setup

Windows quick start

.\setup_threads_archiver_windows.bat

This creates .venv, installs Python dependencies, and installs Playwright Chromium.

Configuration

Preferred options for the vault path, in resolution order:

1. --vault
2. THREADS_ARCHIVER_VAULT
3. threads-archiver.config.json
4. km-config.json as backward-compatible fallback only

Example config:

{
  "vaultPath": "C:/path/to/your/obsidian/vault"
}

Copy tools/threads-archiver.config.example.json to tools/threads-archiver.config.json or threads-archiver.config.json at the repo root and set your vault path.

Login

For the best self-reply capture quality, use a persistent logged-in browser profile:

python .\tools\archive_threads.py login --profile-dir $HOME\.threads_profile

Usage

CLI mode

Recent sync:

python .\tools\archive_threads.py --account @username recent --days 7 --profile-dir $HOME\.threads_profile

The archiver uses Playwright Chromium.

Weekly / overlap sync:

python .\tools\archive_threads.py --account @username weekly --overlap-posts 150 --profile-dir $HOME\.threads_profile

Build index:

python .\tools\build_threads_index.py --account @username

Retry media:

python .\tools\retry_threads_media.py --account @username

GUI mode

Launch the desktop GUI:

.\run_threads_gui.bat

The GUI can run recent syncs, weekly syncs, note refresh tasks, and post-processing steps without writing CLI commands manually.

On macOS, the GUI will only work if the active Python build includes tkinter.

Skill mode

Use the Threads Archiver skill entrypoints when running from an agent environment:

python .\.agent\skills\threads-archiver\scripts\archive_threads.py --account @username recent --days 7 --profile-dir $HOME\.threads_profile

Skill mode is intentionally thin. The scripts in .agent/skills/threads-archiver/scripts/ forward into tools/, so behavior stays aligned with the repo SSOT.

Output structure

Typical output lives under:

ThreadsArchive/<account>/
  ledger/
    posts.jsonl
    runs.jsonl
  notes/
    posts/*.md
  media/
    <stable_id>/*

This split keeps machine-friendly append-only history separate from human-readable notes.

Low-token automation note

This repo is intentionally useful in agentic workflows because it avoids using LLM tokens for the repetitive parts of archival work.

• profile scanning is done by Playwright
• post extraction is done by local Python code
• deduplication is handled by local ledgers
• markdown generation is deterministic and filesystem-based

That makes it a good fit for recurring automation, agent-triggered runs, and long-lived archival jobs where token efficiency matters.

Related utilities

• tools/rebuild_notes_from_ledger.py
• tools/refresh_threads_notes.py
• tools/merge_threads_reply_notes.py
• tools/write_km_threadsarchive_notes.py

Notes

• An authenticated profile is strongly recommended for better capture quality.
• km-config.json is no longer required for standalone deployment.
• Public repo users should keep local config and cookies out of Git. The default ignore rules already cover common secret-bearing files.