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):
- Git repo name:
basename $(git rev-parse --show-toplevel)
- Current directory name:
basename $PWD (fallback if not in a git repo)
Sync targets are derived from the project name:
- Markdown:
{OBSIDIAN_VAULT}/[Project] {project_name}/
- Canvas:
{OBSIDIAN_VAULT}/[Project] {project_name}/canvas/
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
$ARGUMENTS[0]: Type — plan or report (required)$ARGUMENTS[1]: Custom title (optional — auto-inferred from content if omitted)
Execution Flow
Step 0: Detect Project
- Run
basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $PWD to get project name
- Set
PROJECT_DIR = [Project] {project_name}
- Set
CANVAS_DIR = [Project] {project_name}/canvas
- Run
mkdir -p to ensure both directories exist
When type = plan
- Read the latest
.md file from .claude/plans/
- If no plan file found, extract plan content from the current conversation context
- Convert to Obsidian note format (see templates below)
- Write Markdown to
{OBSIDIAN_VAULT}/{PROJECT_DIR}/
- Write Canvas to
{OBSIDIAN_VAULT}/{CANVAS_DIR}/
- Filename:
[Plan] {title} ({YYYY-MM-DD}).md / .canvas
When type = report
- Summarize the implementation work completed in the current session
- Include: what was done, which files changed, key design decisions, follow-up TODOs
- Convert to Obsidian note format
- Write Markdown to
{OBSIDIAN_VAULT}/{PROJECT_DIR}/
- Write Canvas to
{OBSIDIAN_VAULT}/{CANVAS_DIR}/
- 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:
grp_summary (color:4 cyan) — Summary: title + date + 1-3 sentence overviewgrp_work (color:6 pink) — Completed work: split into sub-cards (steps, rules, etc.)grp_files (color:5 purple) — File changes: table of files and operationsgrp_decisions (color:3 green) — Design decisions: architecture/tech choices and rationalegrp_todo (color:2 orange) — Follow-up TODO: checklist of next steps
Plan Canvas layout:
grp_overview (color:4) — Plan overview and goalsgrp_steps (color:6) — Implementation steps, one text node per stepgrp_architecture (color:3) — Architecture/tech decisionsgrp_risks (color:2) — Risks and considerations
Layout principles:
- Groups connected by edges showing flow direction
- Top-left start: Summary → Work/Steps → Files/Architecture → TODO
- Color key: 1=red, 2=orange, 3=green, 4=cyan, 5=purple, 6=pink
Sizing rules (prevent content clipping):
- Text node min width 320px, recommended 500-660px
- Estimate 35px per line of text (including line spacing)
- Headers (##) at 45px, code blocks at 28px per line
- Text node height = line_count × 35 + 60 (top/bottom padding)
- Groups add 20px padding around contained text nodes
- Minimum 80px gap between groups (vertical and horizontal)
- Better too large than too small — clipping is worse than whitespace
Important Rules
- No YAML frontmatter — use
> quote blocks for metadata instead
- Quote blocks for metadata — date, source, status, project in
> blocks
- Preserve original plan content — never trim or rewrite technical details
- Reports must be specific — list actual file paths, code patterns, design rationale
- Always output both files — Markdown + Canvas on every sync
- Report full paths — tell the user where both files were written
- 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
