Skip to main content
command CX Codex

obsidian-architect — Claude Code command: scan code

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.

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-architect does

obsidian-architect turns a codebase into a maintained set of architecture notes — so you (and a future agent) can answer “how does this project work and why” without re-reading the source.

The command runs in two stages. First, a Python scan extracts facts deterministically: languages, modules, dependencies, entry points, signals like Dockerfile or CI config. Then you synthesize prose, rationale, and diagrams. The command never invents structure that the code does not show.

Output is three note types: an architecture overview with Mermaid diagram and personas, one note per core module, and a decisions log. On re-run, only generated sections (marked <!-- @generated -->) update; your own additions stay intact.

What it helps with

  • understand a codebase's architecture without reading all the source
  • document a project so an agent can navigate it later
  • keep architecture notes current after major code changes
  • capture and explain the key design decisions that shaped the project

Example prompts for the agent

  • Run /obsidian-architect ./src and write the architecture into my vault
  • Refresh the architecture notes for the project in ../backend
  • Generate architecture docs with module breakdown and a data flow diagram

How to install obsidian-architect

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-architect.md

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

Questions about obsidian-architect

How do I install obsidian-architect in Claude Code?

Run /plugin marketplace add eugeniughelbur/obsidian-second-brain, then /plugin install obsidian-second-brain@obsidian-second-brain. The command becomes available once the plugin loads.

What does obsidian-architect do?

It scans your project, extracts modules, dependencies, and DevOps signals (Dockerfile, Makefile, CI config), then creates Obsidian notes: an overview with a Mermaid diagram, one note per module, and a log of key decisions from the repo history.

Will re-running the command overwrite my own notes?

No. Generated content is wrapped in <!-- @generated:start/end --> markers. On a re-run, only content inside those markers updates; everything else, including your annotations, stays as-is.

Source text

obsidian-architect.md · MIT
---
description: Scan a codebase and write a maintained set of architecture notes into the vault - overview, per-module notes, key decisions. Re-run to refresh without clobbering your edits
category: meta
triggers_en: ["document this codebase", "architect this project", "map this code into my vault", "generate architecture notes", "refresh architecture docs"]
triggers_de: ["diese Codebasis dokumentieren", "dieses Projekt architektonisch erfassen", "diesen Code in meinem Vault abbilden", "Architekturnotizen erstellen", "Architekturdokumentation aktualisieren"]
triggers_es: ["documenta este código", "analiza la arquitectura de este proyecto", "lleva este código a mi vault", "genera notas de arquitectura", "actualiza la documentación de arquitectura", "pon la arquitectura en el vault"]
triggers_pt: ["documente este código", "arquitete este projeto", "mapeie este código no vault", "gere notas de arquitetura", "atualize a documentação de arquitetura"]
triggers_zh: ["给这个代码库写架构文档", "分析这个项目的架构", "把代码结构整理进知识库", "生成架构笔记", "更新架构文档"]
---

Use the obsidian-second-brain skill. Execute `/obsidian-architect [path-to-codebase]`:

Turns a software project into a maintained set of architecture notes in the vault, so future-you (and future agent) can answer "how does this project work and why" without re-reading the code. Re-running refreshes the notes in place.

This is a hybrid command: a deterministic Python scan produces the facts, then YOU synthesize the prose, rationale, and diagram. Never invent structure the scan did not find (see the anti-fabrication rule).

1. **Resolve the codebase path.** Use the argument if given. Otherwise infer from the active project note's `local-path`, or ask. Confirm it is a directory.

2. **Run the scan** from the skill root (its absolute path was given at session start as **Skill root**; substitute it for `SKILL_ROOT`):
   ```bash
   uv run --directory "SKILL_ROOT" scripts/architect_scan.py --path <codebase>
   ```
   It returns JSON: `name`, `kind`, `languages` (with file counts), `modules` (proposed top-level parts with a `core`/`support` hint), `dependencies`, `entry_points`, `signals` (dockerfile/makefile/ci), and `git` (commit). It writes nothing and calls no LLM - the synthesis is yours.

3. **Optionally pull decision history** for the "Key decisions" note:
   ```bash
   uv run --directory "SKILL_ROOT" scripts/mine_commit_decisions.py --repo <codebase> --json
   ```

4. **Pick the destination.** Write under the project's hub: `<projects folder>/<name>/Architecture/`, with the projects folder resolved per `references/folder-map.md` (wiki-style `wiki/projects/`, Obsidian-style `Projects/`); create it if missing. If the vault has no project note for this codebase yet, offer to create one via `/obsidian-project` first so the architecture links into it.

5. **Synthesize and write these notes**, each AI-first compliant:
   - **`Architecture - Overview.md`** (`type: architecture-overview`): what the project is, its stack (from `languages`/`kind`/`dependencies`), how the parts fit together, and ONE Mermaid diagram of the modules and their main flow. Include a short **Personas** section (2-4 likely user types, marked `confidence: speculation` unless a README states them). Link to each module note.
   - **One note per `core` module** (`type: architecture-module`): `Architecture - <Module>.md` - what it does, what it depends on, and its role in the whole. Keep `support` modules to a single line in the overview unless they are substantial.
   - **`Architecture - Key decisions.md`** (`type: adr` entries or a decisions list): write up the candidates from the commit-decisions miner, each as a real decision with context. Mark anything inferred as `confidence: speculation`.

6. **Sentinel-safe writing (so refresh never destroys your edits).** Wrap every machine-generated section between markers:
   ```
   <!-- @generated:start -->
   ...synthesized content...
   <!-- @generated:end -->
   ```
   Anything a human adds should go in a `<!-- @user:start -->` ... `<!-- @user:end -->` block, or simply outside the generated markers. **On a re-run, replace ONLY the content inside `@generated` blocks; never touch `@user` blocks or anything outside the markers.** If a note has no markers yet (first run), add them around what you generate.

7. **Refresh behavior.** If the architecture notes already exist, this is a refresh: re-scan, then update only the generated blocks whose underlying facts changed (new module, dropped dependency, etc.). Note in the overview's frontmatter the `scanned-commit` so a reader knows how current the docs are. Report what changed.

8. Link the overview from the project note and from today's daily note. Append a one-line entry to the operation log.

---

**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md` - `## For future agent` preamble, rich frontmatter (`type`, `date`, `tags`, `ai-first: true`, plus type-specific fields), recency markers per external claim, mandatory `[[wikilinks]]` for every person/project/concept referenced, sources preserved verbatim with URLs inline, and confidence levels where applicable. 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. The vault is for future agent retrieval - not human reading.

**Anti-fabrication:** Describe only what the scan and the code actually show - never invent a module, a dependency, a data flow, or a decision that is not grounded in the manifest or the source. If the scan is thin (small project, no manifest), say so and keep the notes short rather than padding. Mark inferred rationale and personas as `confidence: speculation`. 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 Agent setup: memory, context, orchestration →

From the same set51

The whole set →
obsidian-projects 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. 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-reconcile obsidian-reconcile is a Claude Code command that finds contradictions in an Obsidian vault and resolves them automatically or flags them for review. It scans the full vault or a specific topic. CX Codex +1 ★ 5,412repo stars obsidian-visualize The obsidian-visualize command maps your Obsidian vault visually: shows how notes connect, identifies hubs, and highlights isolated entries. Use it to see your second brain's shape at a glance. CX Codex +1 ★ 5,412repo stars obsidian-distill obsidian-distill condenses a long note or article into key claims, each tagged with the exact source block it came from — paragraph, section, or timestamp. CX Codex +1 ★ 5,412repo stars obsidian-merge obsidian-merge merges near-duplicate Obsidian notes without deleting files. It preserves links, unions frontmatter, and converts the retired note into a redirect stub. CX Codex +1 ★ 5,412repo stars

Project sponsors

Companies that keep this analytics open