Most productivity systems break at the bridge between planning and doing. You set yearly goals in January, track tasks in a separate app, and review progress—if at all—months later. The connection frays. Goals become aspirational wallpaper. Daily work drifts from stated priorities. For developers who already live in code and markdown↗ Smart Converter, this fragmentation is especially galling: we automate CI/CD pipelines, yet our personal execution remains manual and disjointed.
ballred/obsidian-claude-pkm addresses this directly. It is not a generic note-taking template but an execution system that chains your 3-year vision through yearly goals, projects, monthly milestones, weekly reviews, and daily tasks—with Claude Code as an accountability layer. The focus keyword ballred/obsidian-claude-pkm describes a repository that has accumulated 1,562 stars and 104 forks, suggesting resonance among developers seeking structured, AI-assisted personal knowledge management.
What is ballred/obsidian-claude-pkm?
ballred/obsidian-claude-pkm is an open-source starter kit (MIT License, last updated February 18, 2026) that integrates Obsidian—the popular markdown-based knowledge base—with Anthropic's Claude Code CLI. The repository is primarily Shell-based, reflecting its philosophy of zero dependencies: everything runs on bash and markdown, without additional frameworks or services to maintain.
The project occupies a specific niche: it is neither a standalone application nor a simple Obsidian plugin, but a vault architecture with embedded AI skills. The maintainer, ballred, describes it explicitly as "not another PKM starter kit" but an "execution system." This distinction matters. Where most PKM templates provide folder structures and wish you luck, this system enforces linkage across temporal scales—vision to daily tasks—and uses Claude Code slash commands to automate reviews, flag misalignment, and maintain continuity.
The repository's traction (1,562 stars, active development through early 2026) indicates demand for systems that close the loop between goal-setting and execution. Its relevance now stems from two converging trends: developers' growing adoption of AI coding assistants for workflow automation, and the recognized failure of siloed productivity tools to maintain context across planning horizons.
Key Features
Cascade Architecture — The system's defining structure links six temporal layers: Three-Year Vision → Yearly Goals → Projects → Monthly Goals → Weekly Review → Daily Tasks. Each layer references the next; no planning horizon floats disconnected. The /project new command explicitly bridges goals to active initiatives.
Slash Command Skills — Ten embedded skills automate workflow phases:
/dailyfor morning planning and evening reflection/weeklyfor 30-minute project rollup reviews/monthlyfor quarterly milestone checking/projectfor initiative creation and status dashboards/reviewas a context-aware router (detects morning/Sunday/month-end)/pushfor Git commit/push of vault changes/onboardand/adoptfor setup scenarios/upgradefor version migration with backup
Four Specialized AI Agents — Cross-session memory enables pattern learning:
goal-aligner: Audits daily activity against stated goals; flags recurring misalignmentweekly-reviewer: Facilitates structured weekly reviews; adapts reflection questionsnote-organizer: Maintains vault hygiene—fixes links, consolidates duplicatesinbox-processor: GTD-style categorization and clarification
Zero-Dependency Automation — Bash-based hooks handle auto-commit on file writes, session initialization surfacing active priorities, and skill discovery. No package managers, no background services.
Productivity Coach Output Style — /output-style coach transforms Claude into an accountability partner that challenges assumptions and questions goal-action alignment.
Existing Vault Adoption — The /adopt command scans your current Obsidian structure, detects organization methods (PARA, Zettelkasten, LYT), and generates configuration without touching your folders.
Use Cases
Long-Term Goal Execution for Independent Developers — Freelancers and indie hackers often lack external accountability structures. The cascade forces explicit linkage between revenue targets (yearly), product launches (projects), and daily shipping (tasks). The goal-aligner agent flags when two weeks of "urgent client work" have zero connection to stated strategic priorities.
Research Tracking for ML Practitioners — Paper reading, experiment design, and publication timelines span months. The monthly/quarterly milestone checking ensures that "exploring transformers" as a 3-year vision actually produces conference submissions, not an endless backlog of annotated PDFs.
Team Lead Personal Organization — Engineering managers balancing 1:1s, roadmap planning, and incident response benefit from the weekly review's automated project rollup. The /weekly command reads all daily notes and calculates progress—reducing the Sunday-evening administrative burden.
Content Creator Pipeline — Writers and educators with multi-platform publishing schedules use the project layer to track content series, the monthly layer to align with audience growth goals, and /daily to surface the single most important creative task amid distribution logistics.
Existing Vault Modernization — Developers with years of Obsidian notes resist migration. The /adopt command enables incremental enhancement—adding AI accountability to established structures without the friction of starting fresh.
Installation & Setup
Prerequisites
- Obsidian installed
- Claude Code CLI installed
- Git installed
New Vault Setup
# Clone and set up
git clone https://github.com/ballred/obsidian-claude-pkm.git
cd obsidian-claude-pkm
chmod +x scripts/setup.sh && ./scripts/setup.sh
# Open vault in Obsidian, then start Claude Code:
cd ~/your-vault-location
claude
Step-by-step explanation: The git clone retrieves the repository. chmod +x ensures the setup script is executable—necessary because the repository distributes shell scripts. ./scripts/setup.sh creates the vault structure, installs hooks, and configures permissions. After opening the vault in Obsidian, cd to the vault directory and launch claude to initialize the Claude Code context.
On first run, a welcome message displays the cascade visualization. Run /onboard to personalize: the interactive setup requests your name, preferred review day, and goal areas, then generates all configuration files.
Existing Vault Adoption
cd ~/your-existing-vault
claude
# then type: /adopt
The /adopt command scans your folder structure, detects your organization method interactively, maps folders, and generates scoped configuration files. Your existing directory names are preserved; no content moves.
Windows Installation
git clone https://github.com/ballred/obsidian-claude-pkm.git
cd obsidian-claude-pkm
scripts\setup.bat
Windows users use the batch file equivalent. The repository provides platform-specific setup scripts to handle path and permission differences.
Real Code Examples
Example 1: Agent Invocation for Goal Alignment Analysis
The README documents direct agent invocation through Claude Code:
claude "Use the goal-aligner agent to analyze my last 2 weeks"
This command activates the goal-aligner agent with its cross-session memory. The agent examines your Daily Notes and Project files from the past fourteen days, comparing actual activity against the goals declared in Goals/0. Three Year Goals.md and Goals/1. Yearly Goals.md. It surfaces patterns—recurring misalignment between stated technical learning goals and actual ticket work, for instance—and flags them explicitly rather than assuming alignment. The memory: project configuration means the agent retains these patterns across Claude sessions, refining its understanding of your typical drift vectors.
Example 2: Inbox Processing Automation
claude "Use the inbox-processor agent to clear my inbox"
The inbox-processor implements GTD-style triage on your Inbox/ folder. It categorizes captures against your project structure, clarifies actionable items (what's the next physical action?), and organizes references into appropriate project or archive locations. This is particularly valuable for developers using Obsidian's quick-capture features during meetings or deep-work sessions, where later processing often stalls.
Example 3: Productivity Coach Mode Activation
/output-style coach
After activation, all subsequent interactions adopt an accountability framing. The coach challenges assumptions in your /daily planning ("You marked 'refactor auth service' as your ONE Big Thing, but your yearly goal emphasizes shipping user-facing features—walk me through the alignment"), asks powerful questions, and references prior commitments. This pairs naturally with /daily morning planning and /weekly review sessions.
Example 4: Upgrade with Backup Verification
/upgrade check # Preview what's changed
/upgrade # Interactive upgrade with backup
The upgrade skill creates a timestamped backup before applying changes, displays diffs per file, and explicitly excludes content folders (Daily Notes/, Goals/, Projects/, etc.) from modification. This protects your accumulated work while allowing system improvements. The two-phase approach (check then execute) lets developers review changes in their specific context before committing.
Advanced Usage & Best Practices
Git Integration as Audit Trail — The auto-commit hook triggers on every file write via PostToolUse. This creates implicit journaling: you can git log --since="2 weeks ago" to see exactly when goals shifted, projects were created, or daily notes abandoned. Consider periodic git push via /push or automated remote configuration for backup.
Agent Composition — The documented agents work sequentially. A productive pattern: run inbox-processor to clear capture debt, then goal-aligner to assess whether the resulting organized tasks actually serve stated priorities, then weekly-reviewer to integrate findings into your Sunday routine.
Path-Specific Rules Loading — The .claude/rules/ directory contains conventions loaded contextually based on your current file location. Review these rules periodically—they encode markdown standards and workflow conventions that maintain consistency across AI-generated and human-written content.
Review Day Calibration — The /onboard configuration sets your preferred review day, but this is not immutable. If your schedule shifts (sprint planning moves to Mondays, for instance), manually edit .claude/settings.json or re-run /onboard rather than tolerating misaligned weekly review timing.
Vault Hygiene Scheduling — The note-organizer agent fixes broken links and consolidates duplicates, but benefits from explicit scheduling. Consider a monthly claude "Use the note-organizer agent" invocation, or tie it to your /monthly review cadence.
Comparison with Alternatives
| Tool | Approach | AI Integration | Existing Vault Support | Dependencies |
|---|---|---|---|---|
| ballred/obsidian-claude-pkm | Cascade-linked execution system | Native Claude Code skills/agents | /adopt command |
Zero (bash/markdown) |
| Obsidian + Dataview plugin | Query-based dashboards | None native; manual API integration | N/A (native Obsidian) | Dataview plugin |
| Notion AI | All-in-one workspace | Embedded, generic | Import/export only | Notion platform |
| Logseq + GPT plugins | Outliner-based PKM | Plugin-dependent, variable quality | N/A (native Logseq) | Plugin ecosystem |
Trade-offs to consider:
-
vs. Dataview: Dataview offers powerful querying but requires manual query construction and has no native goal-alignment logic. ballred/obsidian-claude-pkm provides structured commands but less ad-hoc flexibility.
-
vs. Notion AI: Notion offers smoother collaboration and mobile experience. ballred/obsidian-claude-pkm keeps data local (markdown files, Git-backed) and offers deeper Claude Code integration for developers already using that CLI.
-
vs. Logseq: Logseq's outliner structure suits some thinking styles better than Obsidian's file-based approach. The
/adoptcommand partially mitigates this by mapping existing structures, but fundamental paradigm differences remain.
FAQ
Does this require a paid Claude subscription? Claude Code CLI requires Anthropic API access; costs depend on usage volume. The repository itself is MIT-licensed and free.
Will /adopt modify my existing notes?
No. The command scans structure and generates configuration files only. Your content folders remain untouched.
What happens if Claude Code is unavailable? The vault functions as standard Obsidian markdown. AI features degrade gracefully; your data is never locked to the AI layer.
Is Windows fully supported?
Yes, with scripts\setup.bat provided. Some hook behaviors may vary; the README directs Windows users to this path.
How does the auto-commit hook handle merge conflicts? The README does not specify merge conflict resolution. For multi-device use, establish a pull-before-push workflow or use Git's rerere.
Can I use this with my company's Obsidian vault? The MIT License permits commercial use. Verify your organization's AI tooling policies regarding Claude Code specifically.
What if I want to stop using the AI features?
Delete or rename .claude/. The markdown files and folder structure remain fully functional in Obsidian.
Conclusion
ballred/obsidian-claude-pkm solves a specific, underaddressed problem: maintaining coherent linkage between long-term goals and daily execution without adding maintenance burden. Its zero-dependency philosophy, existing-vault adoption path, and cross-session agent memory distinguish it from both generic templates and proprietary platforms.
This system best serves developers already using Obsidian who recognize that their note-taking has outgrown their action-taking. It rewards users willing to engage with structured review cadences and tolerate the explicit accountability that AI agents provide. The 1,562 stars suggest many find this trade worthwhile.
If your goals, projects, and daily tasks currently live in disconnected systems—or if your Obsidian vault has become a graveyard of good intentions—explore ballred/obsidian-claude-pkm on GitHub. Run /adopt on your existing vault or start fresh with ./scripts/setup.sh, and test whether the cascade architecture changes your execution as it has for others.
For related approaches to developer productivity automation, see [INTERNAL_LINK: AI-assisted workflow tools for engineering teams].
