Skip to main content
command CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brain
Open on GitHub

What 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-brain

2Manually: put the files in place

.claude/commands/obsidian-projects.md

Call it with /obsidian-projects. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Notes, tasks and projects →

From the same set51

The whole set →
obsidian-save obsidian-save extracts decisions, tasks, ideas, and contacts from a Claude Code session directly into an Obsidian vault. Useful for archiving working context without manual note-taking. CX Codex +1 ★ 5,412repo stars obsidian-learn The obsidian-learn command reviews lessons in an Obsidian vault, marks stale or replaced findings, and surfaces repeated patterns for _CLAUDE.md. CX Codex +1 ★ 5,412repo stars obsidian-catchup obsidian-catchup — a command to review everything you dumped into the Telegram journal bot on the go—voice, text, images, PDFs, links—and integrate it into your Obsidian vault with Claude Code when you're back at the laptop. CX Codex +1 ★ 5,412repo stars obsidian-retrieval-eval obsidian-retrieval-eval evaluates Obsidian vault search quality using recall@k and MRR metrics. It tests search ranking against natural-language questions before changing indexing. CX Codex +1 ★ 5,412repo stars obsidian-brainstorm obsidian-brainstorm is a Claude Code command that interviews you about an idea one question at a time, then writes a design note with alternatives and a recommendation. CX Codex +1 ★ 5,412repo stars podcast Extracts podcast episode metadata, transcript, and structured summary directly into an Obsidian vault note. CX Codex +1 ★ 5,412repo stars youtube Pulls a YouTube transcript, metadata, and top comments into an Obsidian note. Add --visual when the video’s frames matter too. CX Codex +1 ★ 5,412repo stars obsidian-architect obsidian-architect scans a project and generates architecture notes in your vault: overview with diagram, per-module notes, key decisions. Re-run to refresh docs without losing your edits. CX Codex +1 ★ 5,412repo stars

Project sponsors

Companies that keep this analytics open