# PST to AI Converter
A local CLI tool that converts Microsoft Outlook `.pst` files into AI-friendly formats (Markdown, JSON, or CSV).
## Requirements
- **Python 3.8+**
- **libpst** (install via [Homebrew](https://brew.sh/) on macOS)
## Installation
```bash
brew install libpst
```
No Python packages needed (stdlib only).
## Usage
```bash
# Metadata-only export (default) - compact, token-efficient
python -m pst_converter.cli your_archive.pst
# Full export with email bodies
python -m pst_converter.cli your_archive.pst --full
# Different formats
python -m pst_converter.cli your_archive.pst -f json
python -m pst_converter.cli your_archive.pst -f csv
python -m pst_converter.cli your_archive.pst -f all # md + json + csv
# Include thread linking info (message IDs, references)
python -m pst_converter.cli your_archive.pst --include-threading
# Preserve folder structure (separate files per folder)
python -m pst_converter.cli your_archive.pst --folders
```
## Options
| Option | Description | Default |
| --------------------- | ----------------------------------------------- | ---------- |
| `-f, --format` | `markdown`, `json`, `csv`, `both`, or `all` | `markdown` |
| `--metadata-only` | Headers only, no body content (token efficient) | **On** |
| `--full` | Include full email bodies | Off |
| `--include-threading` | Include message_id, in_reply_to, references | Off |
| `--folders` | Separate files per folder | Off |
| `-o, --output` | Output directory | `./output` |
| `--limit N` | Limit emails (for testing) | None |
| `-v, --verbose` | Verbose logging | Off |
## Format Comparison (5,937 emails)
| Format | Size | Best For |
| ------------ | --------- | ----------------------------------------- |
| **Markdown** | **668KB** | Chat-based AI (most compact) |
| CSV | 1.0MB | Spreadsheets, SQL queries |
| JSON | 1.8MB | Programmatic analysis, structured queries |
**Recommendation**: Use **markdown** for pasting into AI chat, **JSON** for tool-based analysis.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Agent Skill Usage
You can use this as an [Agent Skill](https://code.claude.com/docs/en/skills) by copying the `pst_converter` folder as a skill. This enables AI agents like Claude Code to autonomously convert and analyze PST files.
The `pst_converter/` directory contains:
- `SKILL.md`: Instructions that teach Claude how and when to use the tool.
- `cli.py`: The main entry point script.
- Core logic for extraction and formatting.
### Installation
To install the PST Converter as a **Personal Skill** (available everywhere):
**Option 1: Symlink (Best for development)**
Link the folder to your global skills directory:
```bash
ln -s "$(pwd)/pst_converter" ~/.claude/skills/pst-converter
```
**Option 2: Copy Folder**
Copy the package into your global skills directory:
```bash
cp -r pst_converter ~/.claude/skills/
```
### Verification & Usage
1. **Verify**: In Claude Code, ask: _"What skills do you have available?"_ or _"List my skills"_. You should see `pst-converter` in the list.
2. **Use**: Simply ask Claude to process a PST file. For example:
- _"Convert this archive.pst to markdown"_
- _"Show me a summary of the emails in backup.pst"_
- _"Extract the metadata from archive.pst to a JSON file"_
Claude will autonomously recognize the task, trigger the skill, and handle the command-line execution for you.
> **Note**: Ensure `libpst` is installed on your system, as the skill relies on the `readpst` command.