Nexus AI Chat Importer

📑 Table of Contents

🚀 Getting Started

⚡ Quickstart - Get up and running in 2 minutes
📥 Installation - Install from Community Plugins
📤 Export Your Chats - Get your data from ChatGPT/Claude

💡 Using the Plugin

📥 Import Conversations - Quick or selective import
📊 Import Reports - Understand what was imported
📁 File Organization - Where your files are stored
🎨 Conversation Format - How conversations look

🔧 Advanced

📎 Attachments - Images, DALL-E, artifacts
⚙️ Settings - Customize folders and formatting
🔧 Troubleshooting - Common issues and solutions

📚 More

✨ What's New - v1.3.0 features
☕ Support - Help keep this plugin alive
📜 License - GPL-3.0

⚡ Quickstart

Get started in 2 minutes:

Install the plugin from Obsidian Community Plugins (search "Nexus AI Chat Importer")
Export your chats:
- ChatGPT: Settings → Data controls → Export data → Download ZIP
- Claude: Settings → Export data → Download ZIP
Import: Click the ribbon icon (chat +) in the left sidebar or use command palette → "Import AI conversations"
Select your ZIP file(s) → Choose import mode (all or selective)
Done! Your conversations are now in Nexus/Conversations/

💡 First time? The plugin will show you a welcome dialog with helpful links!

Overview

Import your AI chat conversations from ChatGPT and Claude exports into Obsidian as beautifully formatted Markdown files.

The 1.3.x series brings:

Powerful selective import and better organization (v1.3.0)
Fixes for Claude's new export format (v1.3.2)
A tiny quality-of-life patch for the upgrade notice (v1.3.3)

✨ New in v1.3.0

Selective Import - Choose exactly which conversations to import with interactive preview
Separate Reports Folder - Better organization, easier to exclude from sync
International Date Support - ISO 8601 timestamps work in all languages
Visual Folder Browser - Tree-based navigation, create folders on the fly
Enhanced Attachments - DALL-E images with prompts, better formatting

🎨 Improvements in v1.3.0

Redesigned Settings page - easier to find what you need
Faster imports - especially for large collections
Better progress messages - know exactly what's happening
More detailed reports - see exactly what was imported
Clearer dialogs - less confusing text

🐛 Fixed in v1.3.0

Fixed timestamp parsing for non-US locales
Fixed folder deletion after migration
Fixed link updates in Claude artifacts
Fixed duplicate conversations in multi-ZIP imports
Fixed special characters in conversation titles
And many more...

🐛 Fixed in v1.3.2

Claude changed their export format; the plugin now understands the new structure so Claude artifacts and attachments import correctly again.
If you had missing Claude files, delete the affected Claude notes and re-import the same ZIP after upgrading.

🔹 Quick patch v1.3.3

Fixed the v1.3.2 upgrade notice so it only appears once per vault instead of at every restart.

☕ Support My Work

I'm working on Nexus projects full-time while unemployed and dealing with health issues.

Over 4,300 downloads so far, yet I've received only $20 in donations in the last two months while paying about $200/month out of pocket in expenses.

If this plugin makes your life easier, a donation would mean the world to me and help keep them alive.

Why support?

🚀 Faster development - More time for features and improvements
🐛 Better support - Quicker bug fixes and responses
💡 New features - Your suggestions become reality
❤️ Motivation - Shows that my work is appreciated

Suggested amounts:

$5 - Buy me a coffee ☕ (Thank you!)
$25 - Power my AI development tools 🤖 (Amazing!)
$75 - Supercharge my entire dev toolkit 🚀 (You're a hero!)

Reality check: Over 4,300 downloads, but only $20 in donations over two months. If you use this plugin regularly, please consider contributing. Even $5 makes a real difference! 🙏

✨ Key Features

🎯 Selective Import: Choose exactly which conversations to import with interactive preview
💬 Multi-Provider Support: Full support for ChatGPT and Claude conversations
🎨 Beautiful Formatting: Custom callouts with role-specific colors and icons
📎 Complete Attachment Handling: Images, documents, DALL-E creations with prompts
🎨 Claude Artifact Versioning: Separate files for each artifact modification
📊 Detailed Reports: Comprehensive import statistics with per-file breakdown
🗂️ Flexible Organization: Separate folders for conversations, attachments, and reports
🌍 International Support: ISO 8601 timestamps, works with all locales
⏱️ Progress Tracking: Real-time feedback during large imports
🔄 Smart Deduplication: Handles multiple ZIP files without creating duplicates

📸 See It In Action

💡 Tip: Screenshots coming soon! For now, try the plugin yourself - it's free and takes 2 minutes to set up.

📥 Installation & Settings

Installation Methods

From Obsidian Community Plugins (Recommended):

Open Settings → Community Plugins
Click Browse and search for "Nexus AI Chat Importer"
Click Install, then Enable

Manual Installation:

Download the latest release from GitHub Releases
Extract files to .obsidian/plugins/nexus-ai-chat-importer/
Reload Obsidian and enable the plugin

First-Time Setup

After installing the plugin:

Open Settings → Community Plugins → Nexus AI Chat Importer
Configure your folders (or keep the defaults):
- Conversations: Where your chat notes will be saved
- Attachments: Where images and files will be stored
- Reports: Where import summaries will be created
Configure filename options:
- Add Date Prefix: Enable to add dates to conversation filenames (e.g., 2024-01-15 - My Chat.md)
- Date Format: Choose between YYYY-MM-DD (2024-01-15) or YYYYMMDD (20240115)
Chose message date format:
- Custom date format If Obsidian Locale is not providing the format you want (i.e. english provides US format MM/DD/YYYY), select the format you prefer. The plugin will apply it to messages in conversations while importing

Upgrading from Previous Versions

Good news: The plugin handles everything automatically!

When you upgrade to v1.3.0:

✅ Your settings are migrated to the new format
✅ Your existing conversations are updated with new features
✅ Folders are reorganized if needed (with your permission)
✅ A detailed upgrade report shows you what changed

No manual work required - just install and go!

Plugin Settings

📁 Folder Organization (NEW in v1.3.0)

Choose where your files are stored:

Conversations Folder: Your chat notes (default: Nexus/Conversations)
Attachments Folder: Images, files, and Claude artifacts (default: Nexus/Attachments)
Reports Folder: Import summaries (default: Nexus/Reports)

💡 Tip: You can organize these folders however you like! Put them all together, or spread them across your vault.

🎨 Display Options

Customize how your conversations look:

Date Prefix: Add dates to filenames
- ✅ Enabled: 2024-01-15 - My Conversation.md
- ❌ Disabled: My Conversation.md
Date Format: Choose your style
- With dashes: 2024-01-15
- Without: 20240115
Message Timestamps (NEW in v1.3.0): Choose how dates appear in messages
- Auto (default): Matches your Obsidian language
- Custom: Pick from ISO 8601, US, European, UK, German, or Japanese

🔄 Moving Your Files

Want to reorganize? No problem!

Change a folder path in settings
Click Save
Choose what to do:
- ✅ Move files: Everything moves automatically, links stay working
- ❌ Leave files: They stay put (but won't be managed by the plugin anymore)

💡 Pro tip: The plugin is smart - it merges folders instead of overwriting, so your existing files are safe!

📤 Importing Conversations

Step 1: Get Your Export

ChatGPT:

Open ChatGPT → Settings → Data Controls → Export data
Check your email (arrives in a few minutes)
Download the ZIP file

Claude:

Open Claude → Settings → Privacy → Export data
Check your email (arrives in a few minutes)
Download the ZIP file

Step 2: Import to Obsidian

Two ways to start:

Click the ribbon icon (chat +) in the left sidebar, OR
Press Ctrl/Cmd+P → type "Import AI conversations"

Step 3: Choose Your Import Style

🚀 Quick Import (Import Everything)

Perfect when you want everything imported fast:

Select ChatGPT or Claude
Choose your ZIP file(s)
Click Import All
Done! ✨

🎯 Selective Import (Pick & Choose) - NEW in v1.3.0

Perfect when you want control:

Select ChatGPT or Claude
Choose your ZIP file(s)
Click Select Conversations
Review the list - you'll see:
- 📝 Conversation title and date
- 💬 Number of messages
- 🆕 New / 🔄 Updated / ✅ Already imported
- 📎 Attachments info
Filter conversations (optional):
- 🔍 Search by keyword - Type in the search box to filter by title
- 📊 Filter by status - Show only New, Updated, or Already imported
- 📅 Sort - By date, title, or status
Select conversations:
- ✅ Check individual conversations
- ✅ Use "Select All" / "Deselect All" buttons
- ✅ Use "Select New Only" to import only new conversations
Click Import Selected

Cool features:

✅ Keyword search - Find conversations by title instantly
✅ Smart filtering - Show only what you need
✅ Multi-ZIP support - Process multiple exports at once
✅ Duplicate detection - Automatically finds duplicates across ZIPs
✅ Flexible sorting - Organize by date, title, or status

Step 4: Check Your Report

After every import, you get a beautiful summary report:

What's in it:

✅ How many conversations were imported
⏱️ How long it took
📊 Success rate
📎 Attachment statistics
🔗 Clickable links to your new conversations

Where to find it: <reports>/<provider>/import-YYYYMMDD-HHMMSS.md

💡 Tip: The report opens automatically when import finishes!

📁 Data Organization

Notes

Location

Conversations are organized by provider, year, and month:

<conversations>/
├── <provider>/
│   └── YYYY/
│       └── MM/
│           └── YYYY-MM-DD - conversation-title.md

Example (with date prefix enabled):

<conversations>/chatgpt/2024/01/2024-01-15 - my-conversation.md
<conversations>/claude/2024/02/2024-02-20 - another-chat.md

Example (without date prefix):

<conversations>/chatgpt/2024/01/my-conversation.md
<conversations>/claude/2024/02/another-chat.md

Structure

Each conversation note contains:

1. Frontmatter - Rich metadata for Obsidian features:

---
conversation_id: "abc123..."          # Unique identifier
provider: "chatgpt"                   # chatgpt or claude
title: "Conversation Title"           # Original title
create_time: "2024-01-15T14:30:22Z"  # Creation timestamp (UTC, ISO 8601)
update_time: "2024-01-15T16:45:10Z"  # Last update timestamp (UTC, ISO 8601)
message_count: 42                     # Total messages
aliases: ["Conversation Title"]       # For linking
---

This metadata enables powerful Obsidian features:

🔍 Search & filter by any field
📊 Dataview queries for custom dashboards
📈 Track statistics across conversations
🔗 Link using aliases

2. Header - Title with link to original conversation:

# Conversation Title
[View original conversation](https://chatgpt.com/c/abc123...)

Note: If you deleted the conversation online, the link will be dead.

3. Messages - Formatted with custom callouts:

> [!nexus_user]
> **User** - 2024-01-15 14:30:22
>
> Your message here...

> [!nexus_assistant]
> **Assistant** - 2024-01-15 14:31:05
>
> AI response here...

Callout Types:

👤 nexus_user: Blue callouts for user messages
🤖 nexus_assistant: Green callouts for AI responses
📎 nexus_attachment: Amber callouts for attachments
✨ nexus_artifact: Purple callouts for Claude artifacts
🪄 nexus_prompt: Red callouts for DALL-E prompts

Viewing Modes:

Reading View: Full visual experience with colored callouts
Live Preview: Rendered callouts while editing
Source Mode: Raw Markdown syntax

Date & Time Formats

The plugin uses two different date formats depending on where they appear:

1. Metadata (Top of File) - Universal Format

The dates at the top of each note use ISO 8601 format (2024-01-15T14:30:22.000Z):

✅ Works everywhere - No matter what language you use ✅ Sorts correctly - Alphabetical order = chronological order ✅ No confusion - Never mix up month and day ✅ Works with Dataview - Perfect for queries and tables ✅ Same timezone - Always UTC (no timezone confusion)

2. Message Timestamps (In Conversation) - Your Choice

The timestamps shown in each message can be customized:

Auto (Default): Matches your Obsidian language
- English → 01/15/2024 2:30:22 PM
- French → 15/01/2024 14:30:22
- German → 15.01.2024 14:30:22
Custom (NEW in v1.3.0): Pick your favorite format in Settings
- Universal: 2024-01-15 14:30:22 (same everywhere, easy to sort)
- US: 01/15/2024 2:30:22 PM
- European: 15/01/2024 14:30:22
- German: 15.01.2024 14:30:22
- Japanese: 2024/01/15 14:30:22

⚠️ Important: Changing this setting only affects new imports. Your existing notes won't change (to protect your data).

Example of Universal Format: 2024-01-15T14:30:22.000Z

Date: January 15, 2024
Time: 2:30:22 PM (in UTC timezone)
Why UTC? So the same timestamp works everywhere in the world

Recommendations

✅ DO:

Add your own frontmatter fields (v1.3.0+) - the plugin won't touch them
Edit message content as needed
Use Reading View for best experience

❌ DON'T:

Modify plugin-generated frontmatter fields (conversation_id, provider, etc.)
Delete message IDs (hidden in Reading View)
Remove messages - they'll be restored on reimport

Why? The plugin uses conversation_id and message IDs to detect updates and avoid duplicates. Modifying them breaks this functionality.

Attachments

Location

Attachments are organized by provider:

<attachments>/
└── <provider>/
    ├── images/
    ├── documents/
    └── artifacts/  (Claude only)

Example:

<attachments>/chatgpt/images/dalle-abc123.png
<attachments>/claude/artifacts/conv-id/script_v1.py

What Gets Imported

Images:

User-uploaded photos and screenshots
AI-generated images (DALL-E with prompts)
Embedded directly in conversation notes

Documents:

PDFs, text files, code files
Linked in conversation notes

Claude Artifacts:

Code, documents, and AI-generated content
Saved as separate versioned files
Each modification creates a new version (v1, v2, v3...)

Missing Attachments

Some attachments may be missing from exports:

Older exports: May not include all files
Large files: Sometimes excluded from ZIP
External links: Not downloadable

The plugin continues importing even with missing attachments. Check import reports for details.

🔄 Reimporting & Updates

You can safely reimport the same ZIP file multiple times. The plugin intelligently handles updates:

What Happens:

✅ New conversations → Added
✅ Updated conversations → Refreshed with new messages
✅ Unchanged conversations → Skipped
✅ No duplicates → Smart detection prevents duplicates

When to Reimport:

You've had more conversations since last export
Plugin update adds new features
Fix issues from previous import
Retry failed attachments

What's Updated:

Messages and content
Attachments and artifacts
Frontmatter metadata
Formatting

What's Preserved:

Your manual edits (if frontmatter/message IDs intact)
Existing attachments
Folder structure

⚠️ Important Notes

Projects:

Project organization is not currently supported
All conversations are imported individually
Future versions may add project support

Performance:

Large archives (1000+ conversations) take several minutes to analyze
Obsidian may become temporarily unresponsive during processing
Progress dialogs show real-time status

Storage:

Attachments can significantly increase vault size
AI-generated images can be several MB each
Consider excluding <attachments>/ from cloud sync

🐛 Troubleshooting

Import stuck or slow:

Large archives take 5-10 minutes
Check progress dialog
If frozen, restart Obsidian

No conversations appear:

Verify correct provider selected
Check ZIP file is valid export
Review import report for errors

Safari users (Mac) - ZIP file issues:

Safari automatically unzips downloaded files by default
This creates a folder instead of keeping the ZIP file
Solution: Disable auto-unzip in Safari:
- Safari → Preferences → General
- Uncheck "Open 'safe' files after downloading"
- Re-download the export from ChatGPT/Claude/Le Chat
Note: This is a Safari feature, not a plugin bug
Do NOT manually re-compress unzipped folders (creates incorrect structure)

Missing attachments:

Check import report for details
Older exports may not include all files
Reimport to retry failed attachments

Callouts not displaying:

Use Reading View
Update Obsidian to latest version
Try different theme

Need help?

Check import report for errors
Verify settings are correct
Open issue on GitHub with:
- Plugin & Obsidian versions
- Provider (ChatGPT/Claude)
- Problem description

🚀 Future Plans

We're constantly working to improve the plugin. Here's what's planned for future releases:

Upcoming Features

🤖 New Provider Support:

Mistral Le Chat: Full integration for Mistral AI conversations
Other Providers: Support for any AI provider that offers easily exploitable conversation export files

🌍 Localization:

Multi-language UI: Plugin interface translated into multiple languages
Locale-Aware Formatting: Respect your system locale settings

🎙️ Audio Support:

Voice Conversations: Optional import of audio files from ChatGPT voice conversations
Audio Embedding: Link audio files directly in conversation notes
Transcript Integration: Combine audio with text transcripts

How You Can Help

💡 Suggest Features: Open an issue on GitHub with your ideas
🐛 Report Bugs: Help us improve by reporting issues
☕ Support Development: Buy me a coffee to speed up development
⭐ Star the Repo: Show your support on GitHub

Your feedback and support directly influence what features get prioritized!

📝 License

GNU General Public License v3.0 (GPL-3.0)

This project is licensed under GPL-3.0 starting from version 1.3.0.

What this means:

✅ Free to use - The plugin is and will always be free
✅ Open source - Source code is publicly available
✅ Can modify - You can modify the code for personal use
✅ Can redistribute - You can share modified versions
⚠️ Must share source - Derivative works must also be GPL-3.0 and open source
⚠️ No commercial use without GPL - Commercial derivatives must also be GPL-3.0

Why GPL-3.0?

This license protects the open-source nature of this project while preventing commercial exploitation without giving back to the community. If you create a commercial product based on this code, it must also be open source under GPL-3.0.

Name		Name	Last commit message	Last commit date
assets		assets
dist		dist
docs		docs
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
CLAUDE.md		CLAUDE.md
LICENSE.md		LICENSE.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
esbuild.config.mjs		esbuild.config.mjs
git-history-dev-1.3.0.txt		git-history-dev-1.3.0.txt
git-history-since-1.2.0.txt		git-history-since-1.2.0.txt
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
styles.css		styles.css
tsconfig.json		tsconfig.json
versions.json		versions.json
vitest.config.ts		vitest.config.ts

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Nexus AI Chat Importer

📑 Table of Contents

🚀 Getting Started

💡 Using the Plugin

🔧 Advanced

📚 More

⚡ Quickstart

Overview

✨ New in v1.3.0

🎨 Improvements in v1.3.0

🐛 Fixed in v1.3.0

🐛 Fixed in v1.3.2

🔹 Quick patch v1.3.3

☕ Support My Work

✨ Key Features

📸 See It In Action

📥 Installation & Settings

Installation Methods

First-Time Setup

Upgrading from Previous Versions

Plugin Settings

📁 Folder Organization (NEW in v1.3.0)

🎨 Display Options

🔄 Moving Your Files

📤 Importing Conversations

Step 1: Get Your Export

Step 2: Import to Obsidian

Step 3: Choose Your Import Style

🚀 Quick Import (Import Everything)

🎯 Selective Import (Pick & Choose) - NEW in v1.3.0

Step 4: Check Your Report

📁 Data Organization

Notes

Location

Structure

Date & Time Formats

Recommendations

Attachments

Location

What Gets Imported

Missing Attachments

🔄 Reimporting & Updates

⚠️ Important Notes

🐛 Troubleshooting

🚀 Future Plans

Upcoming Features

How You Can Help

📝 License

🙏 Credits

🔗 Resources

📖 Documentation & Help

💬 Community & Support

📦 Repository

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages