---
name: claude-to-obsidian
description: Export Claude Code conversation transcripts to an Obsidian vault as readable markdown notes. Use when the user wants to save, archive, move, or sync their Claude Code conversations/transcripts/chat history into Obsidian — e.g. "move my claude conversations to obsidian", "export my transcripts", "back up my claude code chats to my vault".
---

# Claude Code → Obsidian

Exports Claude Code conversation transcripts (the JSONL session files under
`~/.claude/projects/`) into an Obsidian vault as readable markdown notes with
kepano-style properties. Each note has `## 🧑 Me` / `## 🤖 Claude` turns, code
preserved, tool calls folded into a collapsible summary, and internal reasoning
omitted. Slash-command and terminal-helper sessions are filtered out.

Self-contained: the bundled `export.py` uses only the Python standard library
(works on Python 3.7+), so no install step is needed.

## How to run

The exporter lives next to this file. Run it with Bash:

```
python3 <SKILL_DIR>/export.py --vault "<vault path>"
```

where `<SKILL_DIR>` is this skill's directory (e.g. `~/.claude/skills/claude-to-obsidian`).

Resolving the vault path:
1. If the user names a vault or one is obvious, pass it via `--vault`.
2. Otherwise omit `--vault` — the script auto-detects a vault (a folder containing
   `.obsidian`) under the home dir, `~/Documents`, and the iCloud Obsidian location.
3. If it reports multiple vaults, ask the user which one and re-run with `--vault`.

Options:
- `--subdir NAME` — write into a subfolder of the vault instead of the root.
- `--dry-run` — list what would be written/pruned without changing anything. Prefer
  running this first if the user is cautious.

After running, report how many conversations were exported.

## Safety

Notes are only created, overwritten, or pruned if they don't exist OR already carry
the `source: claude-code` frontmatter marker. Hand-written vault notes are never
touched. Re-running is idempotent and self-cleaning (stale exports whose transcript
disappeared are removed).

## Notes

- The export reflects transcripts at run time; re-run to refresh. To automate it,
  schedule `export.py` (e.g. a cron job or a macOS launchd agent).
- Set `$CLAUDE_OBSIDIAN_VAULT` to skip passing `--vault` every time.