README.md — Chat Export to Transcript

# Chat Export to Transcript

Chat Export to Transcript converts official local chat exports into a uniform
`messages.jsonl` file and one readable transcript per conversation. It works
with WhatsApp Export chat, Discord Request all of my data, Telegram Desktop
Export chat history JSON, and Slack workspace exports. It reads no app caches,
databases, credentials, or network resources.

## Start

Use Python 3.10 or newer. No packages need installation. Choose an official
export you already have and a new or empty output directory:

```bash
python3 scripts/chat_export_to_transcript.py convert "/path/to/export" --out "/path/to/output" --dry-run
python3 scripts/chat_export_to_transcript.py convert "/path/to/export" --out "/path/to/output" --approve DIGEST_FROM_DRY_RUN
```

The preview lists exact target files and an approval digest. It writes nothing.
The live command creates files only when the digest still matches. Existing
files or symlinks are refused. Use `--format whatsapp|discord|telegram|slack`
when automatic detection is ambiguous. See [SETUP.md](SETUP.md) for usage and
[references/export-formats.md](references/export-formats.md) for accepted
layouts and output schema.

Malformed or unparseable source lines and records are counted and listed.
Their presence marks the result `incomplete` and exits 2; `--allow-partial`
allows exit 0 while retaining the incomplete report. Review skipped records
before treating an export as complete.

## Package

The complete Skills Outpost package includes this skill, the companion agent,
the Python converter, references, and synthetic tests. Run
`python3 -m unittest discover -s tests -v` from the package root. No network
or credentials are required. Tests read shipped package files and create synthetic
fixtures and output files in a temporary folder, then remove that folder. Version 0.1.1, free under the MIT license.

WhatsApp (Meta), Discord, Telegram, and Slack (Salesforce) are trademarks of
their owners. This product is independent and unaffiliated.

## Local safety requirements

Supported platforms are macOS and Linux with Python 3.10 or newer and POSIX
no-follow directory descriptor APIs. Windows and other platforms are refused
before input or output I/O. Paths with symlink components, `..`, or NUL are refused; explicit absolute user paths are allowed. Percent signs and backslashes are literal local filename characters; paths are never URL-decoded. ZIP member names still refuse percent signs and backslashes.
On macOS use the physical path (for example `/private/tmp`, not its alias).

Every read file is limited to 33,554,432 bytes (32 MiB), including the selected
ZIP and its chat TXT member; ZIPs may contain at most 100 members. There is no
stdin input. Every ZIP member name is validated before reading member content;
ZIP members are never extracted. Directory exports enumerate all immediate
channel folders and read all supported message files, plus Discord channel
metadata or Slack users.json; no conversation filter reduces these reads.
Attachment names and reply IDs are retained as metadata, never opened or fetched.

Approval binds the fully resolved destination, its existing directory identity
(device and inode), its parent identity, directory creation, and every output
file's bytes. The digest covers rendered output, not ignored source fields.
The preview lists creation of the destination and transcripts directory. The
immediate output parent must already exist: no ancestors are created. Live
writes walk directories without following symlinks, verify approved identities,
and create files exclusively relative to directory descriptors. Write failures
retain partial output and report an error; choose a fresh output for a retry.

Malformed JSON, ZIPs, nested metadata and attachment shapes fail with an explicit
error. Invalid message records are listed as skipped with incomplete status;
`--allow-partial` explicitly accepts those omissions. Header-shaped WhatsApp
body lines remain ambiguous. This tool does not authenticate source messages,
verify provider export completeness, or verify reply targets; reply IDs are
copied without correlation checks. There is no separate verification command.

Use the physical path when an ancestor is a symlink (for example /private/tmp on macOS).

A symlink anywhere inside an export directory is refused; directory metadata is checked throughout Discord and Slack exports.

Discord transcripts begin with the validated readable channel.json name (or the grouping key if absent), followed by the channel ID; filenames and JSONL conversation keys remain ID-based, falling back to the folder name when the ID is absent. JSONL also includes channel_name (null when absent). Duplicate grouping keys are refused with an error naming both folders.

In Slack root layout, every root subfolder is treated as a channel folder. Its JSON files are parsed even in unrelated folders; invalid JSON fails with exit 2, and invalid records or non-array JSON mark the run incomplete (exit 2 unless --allow-partial). Non-JSON files are ignored.

Discord and Telegram timestamps use the same explicit parser on all supported Python versions: calendar dates YYYY-MM-DD or YYYYMMDD, optionally followed by T or a space and HH:MM or HHMM with optional seconds, arbitrary decimal fractions (dot or comma), and Z or a numeric HH:MM/HHMM offset. Output has whole seconds; fractions are truncated. Other forms and invalid dates are skipped and counted.

By Zero Width Lab (zerowidthlab.com)

License: MIT (read it).

Back to the listing