obsidian-projects — Claude Code command for project status
obsidian-projects is a Claude Code command that builds project status from Obsidian notes, Git, and local docs. Ask for an overview or name one project to inspect.
MIT ★ 5,412 updated 2026-10-24
/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brainWhat obsidian-projects does
The command finds project notes in the vault’s projects folder, then gathers details from each note, its Git repository, and the first available NOTES.md or TODO.md. A request without a project name produces an overview; a named project gets a deeper status report. Activity and explicit blockers inform the status, while note values such as on-hold, completed, or archived take precedence.
The report includes the latest session, a next action, and blockers. It prints the overview in chat and writes or replaces ## Last overview in each project note. Repositories need to be reachable at the paths in repo: for Git checks. Vault edits must follow references/ai-first-rules.md; if the command cannot read that file, it reports the problem before writing. It does not create notes for repositories without a matching project note.
What it helps with
- assemble a status overview from vault notes and Git
- find recent commits and working-tree changes
- extract next steps and blockers from project docs
- write the latest review summary back to project notes
Example prompts for the agent
- Show an overview of all projects in my Obsidian vault.
- What is the status of
Project Name? - Refresh the project overview and write the results to the notes.
How to install obsidian-projects
1Plugin marketplace
/plugin marketplace add eugeniughelbur/obsidian-second-brain/plugin install obsidian-second-brain@obsidian-second-brain2Manually: put the files in place
.claude/commands/obsidian-projects.mdCall it with /obsidian-projects. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/obsidian-projects.mdCall it with /prompts:obsidian-projects. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/obsidian-projects.prompt.mdManually: put the files in place
.gemini/commands/obsidian-projects.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about obsidian-projects
How do I install obsidian-projects in Claude Code?
Run /plugin marketplace add eugeniughelbur/obsidian-second-brain, then /plugin install obsidian-second-brain@obsidian-second-brain.
What does obsidian-projects do?
It gathers project context from Obsidian notes, Git, and NOTES.md or TODO.md files, prints a status overview in chat, and updates each project note’s ## Last overview section.
Does obsidian-projects modify vault notes?
Yes. It writes or replaces ## Last overview in project notes. It does not create a note when a repository has no matching project note.
Source text
obsidian-projects.md · MIT
--- description: Live project status from git + local docs - infers all context from vault notes, no config required category: vault triggers_en: ["projects overview", "project status", "what am I working on", "show projects"] triggers_de: ["Projektübersicht", "Projektstatus", "woran arbeite ich gerade", "Projekte anzeigen"] triggers_es: ["resumen de proyectos", "estado de los proyectos", "en qué estoy trabajando", "muéstrame los proyectos"] triggers_pt: ["visão geral de projetos", "status dos projetos", "em que estou trabalhando", "mostre os projetos"] triggers_zh: ["看看所有项目的状态", "我现在在做哪些项目", "项目进展怎么样", "显示项目总览"] --- Use the obsidian-second-brain skill. Execute `/obsidian-projects $ARGUMENTS`: Optional argument: a specific project name. If given, show deep context for that one project only. If no argument, run the full overview for all tracked projects. ## Step 1 - discover projects Read `_CLAUDE.md` to find the projects folder name, resolved per `references/folder-map.md` (wiki-style `wiki/projects/`, Obsidian-style `Projects/`). If not defined, default to the wiki-style `wiki/projects/`. Scan that folder for all `.md` files. For each file, read its frontmatter. A note is a tracked project if it has `type: project` OR lives in the projects folder and has a `repo:` field. Collect: - `vault_note` - the file path - `name` - from `name:` frontmatter or the filename - `repo` - from `repo:` frontmatter; absent means non-code project (git steps skip) - `status` - from `status:` frontmatter if present If the optional argument was given, filter to the matching project only. ## Step 2 - gather state in parallel Spawn one subagent per project. Each agent runs three checks: **Vault check:** - Read the project note - Extract: `status`, most recent entry in any `Recent Activity` section, `next_action`, open questions, blockers. IGNORE `## Last overview` sections - this command writes those, and reading them back would mark stale projects active forever (a feedback loop) **Git check** (skip if no `repo:` field): - `git -C "<repo>" log --oneline --no-merges -15` - `git -C "<repo>" status --short` - If the path doesn't exist or isn't a git repo, note it and skip **Docs check** (skip if no `repo:` field): - Look for `NOTES.md`, `TODO.md`, `docs/NOTES.md`, `docs/TODO.md` in the repo root - Read the first one found; skip if none exist - Extract explicit next steps, blockers, or context not in the vault note ## Step 3 - synthesize per project Merge the three agent results into one status block per project: - **Status**: infer from activity recency: `active` (commits or vault update in last 7 days, excluding `## Last overview` writes), `stalled` (7-30 days), `idle` (30+ days), `blocked` (explicit blocker found). Override with the note's `status:` field if it says `on-hold`, `completed`, or `archived`. - **Last session**: what was worked on and when. Prefer git commit dates + messages over vault dates. - **Next action**: single most concrete next step. Pull from vault open questions or docs TODO. If unclear, say so - do not invent one. - **Blocked by**: anything explicitly blocking. `none` if nothing found. ## Step 4 - print to conversation Print the full overview in the conversation immediately. Order: active first, then stalled, then idle, then archived. Use this format per project: ``` ## [Project Name] Status: active | stalled | idle | blocked | archived Repo: path/to/repo (or "no repo") Vault: [[<projects folder>/Project Name]] (use the folder resolved in step 1) Last session: YYYY-MM-DD - one sentence on what was done (source: git / vault / docs) Next action: specific next step, or "unclear - check vault note" Blocked by: none | description ``` ## Step 5 - update vault notes For each project note, inject or overwrite a `## Last overview` section with the synthesized status and timestamp. This makes the note self-aware of when it was last reviewed. Use this format: ```markdown ## Last overview **Reviewed:** YYYY-MM-DD (source: /obsidian-projects) **Status:** active | stalled | idle | blocked | archived **Last session:** YYYY-MM-DD - one sentence on what was done (source: git | vault | docs) **Next action:** specific next step, or "unclear - check vault note" **Blocked by:** none | description ``` If a project note doesn't exist yet but was discoverable via git (e.g. the repo folder exists but has no matching vault note), mention it at the end as "untracked repos found". Do not create notes automatically. --- **AI-first rule:** Every vault write MUST follow `references/ai-first-rules.md` - `## For future agent` preamble, rich frontmatter, `[[wikilinks]]` for every project referenced, recency markers on git-sourced facts (e.g. `(as of 2026-05-21, git log)`), sources noted inline. If that path does not resolve from your working directory, search upward for it; if you still cannot read it, say so before writing rather than producing a note that silently skips the rule. **Anti-fabrication:** Search exhaustively before claiming any note, person, or file is absent - false absence is the most common failure mode - and never invent facts, entities, or dates (mark unknowns as `TBD`). See the anti-fabrication and search-completeness hard rules in `references/ai-first-rules.md`.
© Eugeniu Ghelbur · MIT · eugeniughelbur/obsidian-second-brain