Sync Obsidian

Sync to Obsidian — Auto-Detect Project Sync

Automatically sync your Claude Code session plans and implementation reports to your Obsidian vault.

Every sync produces two files: a detailed Markdown note + an Obsidian Canvas visual map.

The project name is auto-detected — no per-project configuration needed.

Configuration

Only one path to set — your Obsidian vault root:

OBSIDIAN_VAULT = /Users/you/Documents/Obsidian Vault

> Update this to your actual Obsidian vault path before first use.

Auto Project Detection

The skill automatically detects the current project name (in priority order):

1. Git repo name: basename $(git rev-parse --show-toplevel) 2. Current directory name: basename $PWD (fallback if not in a git repo)

Sync targets are derived from the project name:

> Directories are auto-created if they don't exist (mkdir -p).

Usage

/sync-obsidian plan               # Sync the latest plan file
/sync-obsidian report             # Generate and sync an implementation report
/sync-obsidian plan Auth Redesign # Sync plan with custom title
/sync-obsidian report API Layer   # Sync report with custom title

Execution Flow

Step 0: Detect Project

1. Run basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $PWD to get project name 2. Set PROJECT_DIR = [Project] {project_name} 3. Set CANVAS_DIR = [Project] {project_name}/canvas 4. Run mkdir -p to ensure both directories exist

When type = plan

1. Read the latest .md file from .claude/plans/ 2. If no plan file found, extract plan content from the current conversation context 3. Convert to Obsidian note format (see templates below) 4. Write Markdown to {OBSIDIAN_VAULT}/{PROJECT_DIR}/ 5. Write Canvas to {OBSIDIAN_VAULT}/{CANVAS_DIR}/ 6. Filename: [Plan] {title} ({YYYY-MM-DD}).md / .canvas

When type = report

1. Summarize the implementation work completed in the current session 2. Include: what was done, which files changed, key design decisions, follow-up TODOs 3. Convert to Obsidian note format 4. Write Markdown to {OBSIDIAN_VAULT}/{PROJECT_DIR}/ 5. Write Canvas to {OBSIDIAN_VAULT}/{CANVAS_DIR}/ 6. Filename: [Report] {title} ({YYYY-MM-DD}).md / .canvas

Markdown Templates

Plan Template

# [Plan] {title}
> Date: {YYYY-MM-DD}
> Source: Claude Code Session
> Project: {project_name}
> Status: Pending / Approved
{Original plan content, preserved in full markdown}
> Synced from .claude/plans/{filename}

Report Template

# [Report] {title}
> Completed: {YYYY-MM-DD}
> Source: Claude Code Session
> Project: {project_name}
Summary
{1-3 sentence overview}
Completed Work
{Detailed list of completed work:}
Files created/modified
Key design decisions
Technical details
File Changes
| File | Action | Description |
|------|--------|-------------|
| ... | Created/Modified | ... |
Design Decisions
{Important architectural/technical decisions and rationale}
Follow-up TODO
[ ] {Next steps}
> Auto-generated by Claude Code

Canvas Sync (Dual Output)

Every Markdown sync also generates an Obsidian Canvas file (.canvas) for visual exploration.

Canvas Structure

Canvas is a JSON format with nodes (cards/groups) and edges (connections).

Report Canvas layout:

Plan Canvas layout:

Layout principles:

Sizing rules (prevent content clipping):

Important Rules

1. No YAML frontmatter — use > quote blocks for metadata instead 2. Quote blocks for metadata — date, source, status, project in > blocks 3. Preserve original plan content — never trim or rewrite technical details 4. Reports must be specific — list actual file paths, code patterns, design rationale 5. Always output both files — Markdown + Canvas on every sync 6. Report full paths — tell the user where both files were written 7. Auto-create directories — use mkdir -p if project or canvas dir doesn't exist

Auto-Sync Setup (Optional)

Add this to your project's CLAUDE.md to enable the full sync lifecycle:

## Auto Sync to Obsidian
Plan Sync (Before Implementation)
When a plan/design discussion is complete and about to move into implementation,
call /sync-obsidian plan FIRST — so the user can review it in Obsidian before
giving the green light.
Trigger when:
A plan or design discussion has been finalized
User indicates approval intent ("looks good", "let's do it")
Before starting any implementation work
Flow: Discuss → Sync plan → User reviews in Obsidian → Confirmed → Implement
Report Sync (After Implementation)
After completing substantive work, call /sync-obsidian report before the session ends.
Trigger when:
Code files were created, edited, or deleted
A plan was implemented
Important architecture discussions or decisions were made
Do NOT trigger when:
Pure Q&A / casual chat
Only read files, no modifications
User explicitly says no sync needed

/sync-obsidian plan               # Sync the latest plan file
/sync-obsidian report             # Generate and sync an implementation report
/sync-obsidian plan Auth Redesign # Sync plan with custom title
/sync-obsidian report API Layer   # Sync report with custom title

Only one path to set — your Obsidian vault root:

OBSIDIAN_VAULT = /Users/you/Documents/Obsidian Vault

> Update this to your actual Obsidian vault path before first use.