obsidian-claude-pkm/README.md

📊 Take the quick poll - Help shape what gets built next!

---

Obsidian + Claude Code PKM Starter Kit 🚀

A complete personal knowledge management system that combines Obsidian's powerful note-taking with Claude Code's AI assistance. Go from zero to a fully functional PKM in 15 minutes or less.

v3.0 - The Cascade: end-to-end goals-to-tasks flow with /project and /monthly skills, agent memory, and agent teams.

✨ Features

Core PKM

• 🎯 Goal-Aligned System - Cascading goals from 3-year vision to daily tasks
• 📅 Daily Notes System - Structured daily planning and reflection
• 📱 Mobile Ready - GitHub integration for notes on any device
• 🔄 Version Controlled - Never lose a thought with automatic Git backups
• 🎨 Fully Customizable - Adapt templates and structure to your needs

AI-Powered (v3.0)

• 🔗 The Cascade - End-to-end flow: 3-year vision → yearly goals → projects → monthly → weekly → daily tasks
• 📁 Project Management - /project skill to create, track, and archive projects linked to goals
• 📆 Monthly Reviews - /monthly skill rolls up weekly reviews, checks quarterly milestones
• 🧠 Agent Memory - Agents learn your vault patterns across sessions (goal-aligner remembers misalignment patterns, weekly-reviewer learns your reflection style)
• 👥 Agent Teams - Parallel weekly reviews with collector, goal-analyzer, and project-scanner agents
• ⚡ Unified Skills - Skills and slash commands merged (/daily, /weekly, /monthly, /project, /push, /onboard)
• 🪝 Hooks - Auto-commit on save, session initialization with priority surfacing
• 🤖 Custom Agents - Note organizer, weekly reviewer, goal aligner, inbox processor
• 📏 Modular Rules - Path-specific conventions for markdown, productivity, projects
• 🎭 Output Styles - Productivity Coach for accountability
• 📊 Status Line - Vault stats in terminal (note count, inbox, uncommitted changes)
• 👁️ Progress Visibility - See spinner updates during multi-step operations like morning routines

🚀 Quick Start

Prerequisites

• Obsidian installed
• Claude Code CLI installed
• Git installed
• GitHub account (optional, for mobile sync)

15-Minute Quickstart

# 1) Install prerequisites (once)
# - Obsidian: https://obsidian.md/
# - Git: https://git-scm.com/
# - Claude Code CLI: https://code.claude.com/docs

# 2) Clone this repository
git clone https://github.com/ballred/obsidian-claude-pkm.git
cd obsidian-claude-pkm

# 3) Run setup (macOS/Linux)
chmod +x scripts/setup.sh
./scripts/setup.sh

# 3b) Windows
scripts\setup.bat

Manual Copy (alternative)

# Copy the vault template to your preferred location
cp -r vault-template ~/Documents/ObsidianPKM

Open in Obsidian

1. Launch Obsidian
2. Click "Open folder as vault"
3. Select your vault folder (e.g., ~/Documents/ObsidianPKM)
4. Start with today's daily note!

📖 Documentation

• Setup Guide - Detailed installation instructions
• Customization - Make it yours
• Workflow Examples - Daily routines and best practices
• Troubleshooting - Common issues and solutions

🗂️ Structure

Your Vault/
├── CLAUDE.md                    # AI context and navigation
├── CLAUDE.local.md.template     # Template for personal overrides
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest
├── .claude/
│   ├── agents/                  # Custom AI agents
│   │   ├── note-organizer.md
│   │   ├── weekly-reviewer.md
│   │   ├── goal-aligner.md
│   │   └── inbox-processor.md
│   ├── skills/                  # Unified skills (invoke with /skill-name)
│   │   ├── daily/               # /daily - Create daily notes, routines
│   │   ├── weekly/              # /weekly - Weekly review process
│   │   ├── monthly/             # /monthly - Monthly review and planning (NEW)
│   │   ├── project/             # /project - Create and track projects (NEW)
│   │   ├── push/                # /push - Git commit and push
│   │   ├── onboard/             # /onboard - Load vault context
│   │   ├── goal-tracking/       # Auto: Track goal progress
│   │   └── obsidian-vault-ops/  # Auto: Vault file operations
│   ├── hooks/                   # Event automation (NEW)
│   │   ├── session-init.sh
│   │   └── auto-commit.sh
│   ├── rules/                   # Path-specific conventions (NEW)
│   │   ├── markdown-standards.md
│   │   ├── productivity-workflow.md
│   │   └── project-management.md
│   ├── scripts/
│   │   └── statusline.sh        # Terminal status display (NEW)
│   ├── output-styles/
│   │   └── coach.md             # Productivity Coach
│   └── settings.json            # Permissions and config (NEW)
├── Daily Notes/
├── Goals/
├── Projects/
├── Templates/
└── Archives/

🧠 Output Styles

This starter kit includes a Productivity Coach output style that transforms Claude into an accountability partner. The coach will:

• Challenge you to clarify your true intentions
• Point out misalignments between stated goals and actions
• Ask powerful questions to drive momentum
• Hold you accountable to your commitments
• Help you identify and overcome resistance

To use the coach style in Claude Code:

1. The output style is automatically included in .claude/output-styles/
2. Start Claude Code and type /output-style to select from available styles
3. Or directly activate with: /output-style coach
4. The style preference is automatically saved for your project

Learn more about customizing output styles.

🔗 The Cascade

The complete goals-to-tasks flow — the #1 requested feature:

3-Year Vision ──→ Yearly Goals ──→ Projects ──→ Monthly Goals ──→ Weekly Review ──→ Daily Tasks
                                      ↑
                              /project new
                         (the bridge layer)

Every layer connects:

• /project new creates a project linked to a yearly goal
• /daily morning routine surfaces your ONE Big Thing + project next-actions
• /weekly review includes a project progress table
• /monthly review rolls up weekly reviews and checks quarterly milestones
• /goal-tracking includes project completion % in goal progress calculations

🤖 Custom Agents (v3.0)

Ask Claude to use specialized agents for common PKM tasks:

# Organize your vault and fix broken links
claude "Use the note-organizer agent to audit my vault"

# Facilitate weekly review aligned with goals
claude "Use the weekly-reviewer agent for my weekly review"

# Check if daily work aligns with long-term goals
claude "Use the goal-aligner agent to analyze my recent activity"

# Process inbox items using GTD principles
claude "Use the inbox-processor agent to clear my inbox"

🔄 Upgrading

From v2.1 to v3.0

# 1. Copy new skill directories
cp -r vault-template/.claude/skills/project your-vault/.claude/skills/
cp -r vault-template/.claude/skills/monthly your-vault/.claude/skills/

# 2. Update existing files (review diff first)
cp vault-template/.claude/settings.json your-vault/.claude/
cp vault-template/.claude/hooks/session-init.sh your-vault/.claude/hooks/

# 3. Update agents (adds memory: project)
cp vault-template/.claude/agents/*.md your-vault/.claude/agents/

# 4. Update existing skills (adds cascade features)
cp -r vault-template/.claude/skills/daily your-vault/.claude/skills/
cp -r vault-template/.claude/skills/weekly your-vault/.claude/skills/
cp -r vault-template/.claude/skills/goal-tracking your-vault/.claude/skills/
cp -r vault-template/.claude/skills/onboard your-vault/.claude/skills/

# 5. Review and merge CLAUDE.md changes
# Add /project and /monthly to your skills table, bump version

# 6. Make scripts executable
chmod +x your-vault/.claude/hooks/*.sh

From v1.x to v3.0

# 1. Copy all new directories to your vault
cp -r vault-template/.claude-plugin your-vault/
cp -r vault-template/.claude/agents your-vault/.claude/
cp -r vault-template/.claude/skills your-vault/.claude/
cp -r vault-template/.claude/hooks your-vault/.claude/
cp -r vault-template/.claude/rules your-vault/.claude/
cp -r vault-template/.claude/scripts your-vault/.claude/
cp vault-template/.claude/settings.json your-vault/.claude/
cp vault-template/CLAUDE.local.md.template your-vault/

# 2. Review and merge CLAUDE.md changes
# Your customizations are preserved, just add references to new features

# 3. Make hook scripts executable
chmod +x your-vault/.claude/hooks/*.sh
chmod +x your-vault/.claude/scripts/*.sh

🤝 Contributing

Found a bug or have a feature idea? Please open an issue or submit a PR!

📄 License

MIT - Use this freely for your personal knowledge management journey.

---

Ready to transform your note-taking? Follow the Setup Guide to get started!