obsidian-docs

AI memory for your codebase.

One command gives Claude Code a persistent, structured memory of your repo — the why behind every module, every architectural decision, every gotcha — and keeps it fresh as you code.

npx obsidian-docs install

[!NOTE] In a real codebase: <X>× faster onboarding · <Y>% fewer “where is X defined?” lookups by Claude · <Z> of architectural decisions captured that would otherwise have been lost. (Numbers from after Z weeks. Run it on yours and tell me — open an issue with your before/after.)

Try it without touching your repo

npx obsidian-docs demo

Spins up a fake project in a temp directory, fully populated with sample modules, ADRs, and a runbook. Open the resulting docs/ folder in Obsidian and switch to graph view — that’s what a healthy obsidian-docs-managed repo looks like.

What it does

Two parties, one source of truth:

Audience	What they see	How they use it
👩‍💻 Humans	An Obsidian vault at `docs/` — browsable graph, wikilinks between notes, search	Onboarding, design rationale, “why did we do it this way?”
🤖 Claude Code	A skill at `.claude/skills/obsidian-docs/SKILL.md` + a section in `CLAUDE.md`	Claude reads the vault for context, writes new notes when you change code, updates the index, never duplicates

Run install once and your repo gets:

📁 An Obsidian vault at docs/ (modules, ADRs, runbooks, architecture)
🎯 A Claude Code skill that enforces strict templates and [[wikilinks]]
📝 A documentation policy injected into CLAUDE.md
🪝 An optional PostToolUse hook that nudges Claude after every Write/Edit

From then on, when you ask Claude “add a NotificationService that calls SendGrid” — Claude writes the code AND creates the module note, links its dependencies, and updates _INDEX.md. In the same commit.

Why?

Code answers what. Memory answers why.

Today, every Claude session starts cold. It re-reads files, re-derives architecture, re-discovers gotchas you’ve explained ten times. That’s wasted context window, wasted latency, wasted attention.

Most repos try to solve this two ways, and both fail:

Failure	What it looks like
No docs	New devs and AI agents both read code blind. Decisions are lost. Onboarding takes weeks. Claude makes the same mistake twice.
Stale docs	A `README.md` graveyard. A Notion page nobody updates. AI agents get told the wrong thing about your system.

obsidian-docs is the third path: structured templates so docs are cheap to write, plus a skill + hook so Claude maintains them in the same commit as the code. Humans browse it as a graph; AI reads it as structured context. It doesn’t drift because it’s not a side project — it’s part of how Claude works in your repo.

Install

# One-off (recommended)
npx obsidian-docs install

# Or install globally
npm install -g obsidian-docs
obsidian-docs install

Requires Node ≥ 18.

What gets created

your-repo/
├── CLAUDE.md                                    ← obsidian-docs section appended
│                                                  (existing content preserved)
├── .claude/
│   ├── skills/obsidian-docs/SKILL.md           ← templates + rules Claude follows
│   └── hooks/obsidian-docs-nudge.sh            ← optional PostToolUse hook
└── docs/                                        ← Obsidian vault
    ├── _INDEX.md                                ← master index
    ├── modules/                                 ← one note per module/service
    ├── decisions/                               ← Architecture Decision Records
    ├── runbooks/                                ← operational procedures
    ├── architecture/                            ← system overviews
    └── .obsidian/                               ← Obsidian app config

Open docs/ in Obsidian to browse it as a linked graph.

Commands

Command	What it does
`obsidian-docs demo`	Spin up a fully-populated demo project so you can see it before installing
`obsidian-docs install`	Scaffold the vault, install the skill, patch `CLAUDE.md`, commit. Safe on existing repos. Pass `--vault-path notes` to use a folder name other than `docs/`.
`obsidian-docs relocate <path>`	Move the vault to a new folder OR re-detect after you renamed it in Obsidian.
`obsidian-docs status`	Health check — are all the pieces in place?
`obsidian-docs update`	Refresh `SKILL.md` to the latest version
`obsidian-docs hook install`	Install a PostToolUse hook that nudges Claude after Write/Edit
`obsidian-docs hook uninstall`	Remove the hook
`obsidian-docs backfill [path]`	Spawn Claude Code to populate `docs/modules/` from existing source
`obsidian-docs uninstall`	Surgical removal — vault, skill, and the marker block from `CLAUDE.md`

Common flags

obsidian-docs install --global       # share one skill across all repos (~/.claude/skills/)
obsidian-docs install --no-git       # skip the auto-commit
obsidian-docs hook install --local   # personal-only (settings.local.json, gitignored)
obsidian-docs uninstall --keep-vault # remove skill + section, keep your notes
obsidian-docs uninstall --yes        # skip confirmation
obsidian-docs backfill --dry-run     # show the prompt without spawning Claude
obsidian-docs backfill src/auth      # scope to a subdirectory

Two scenarios

🆕 New repo

mkdir my-app && cd my-app
git init && npm init -y
obsidian-docs install
# done in 30 seconds

🏚 Existing codebase

The install command is safe to run on any existing repo — it never overwrites your content. It detects what’s there and only fills gaps.

Existing state	What happens
No `CLAUDE.md`, no `docs/`	Creates both from scratch
`CLAUDE.md` exists	Appends section between `<!-- obsidian-docs:start/end -->` markers — original content untouched
`docs/` exists with content	Only creates missing folders/files. Existing notes left alone.
Re-running	Replaces just the marker block in `CLAUDE.md`; leaves vault notes alone; refreshes `SKILL.md`

After install, ask Claude to backfill what’s already there:

obsidian-docs backfill            # auto-targets src/ (or lib/, app/, packages/)
obsidian-docs backfill src/auth   # or batch by area for review

Rename the vault freely

Obsidian’s “Rename vault” silently renames the folder on disk. That’s fine — every obsidian-docs command auto-detects the new location via a marker file (.obsidian-docs-vault) and a config (.obsidian-docs.json) at the repo root.

# You renamed docs/ → SyncForm/ inside Obsidian. Now:
obsidian-docs status
# ↻ Vault relocated: docs → SyncForm — updating references...
# ✓ Updated config + CLAUDE.md to use SyncForm/

The CLI updates the config, rewrites the CLAUDE.md path references, and the PostToolUse hook follows. Zero manual intervention. You can also pre-empt it:

obsidian-docs install --vault-path notes      # use notes/ instead of docs/ from the start
obsidian-docs relocate wiki                   # move docs/ → wiki/ explicitly
obsidian-docs relocate                         # just re-scan and confirm location

How Claude actually uses it

Once installed, you talk to Claude naturally:

> Add a NotificationService that sends emails via SendGrid.

Claude writes the code AND:

Creates docs/modules/NotificationService.md from the template
Updates docs/modules/SendGridClient.md (if it exists) under “Consumed by”
Updates docs/_INDEX.md

> We're switching from REST to gRPC for internal services.

Claude:

Finds the next ADR number (e.g. ADR-007)
Creates docs/decisions/ADR-007-grpc-internal-services.md with context, decision, alternatives
Links it from affected module notes

> Heads up — calling PaymentService.charge() before .authenticate() silently fails.

Claude:

Appends a single bullet to docs/modules/PaymentService.md under “Known gotchas”
Touches nothing else

Templates Claude follows

Module note

# <ModuleName>

## Purpose
What problem does this solve? One paragraph max.

## Owns
- src/path/to/file.ts

## Dependencies
- [[ModuleA]] — reason why

## Consumed by
- [[ModuleC]]

## Key decisions
- [[ADR-001 Title]]

## Known gotchas
- Edge cases that bit us

## Last reviewed
YYYY-MM-DD

ADR

# ADR-<NNN>: <Title>

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Superseded by [[ADR-NNN]]

## Context / Decision / Consequences / Alternatives / Links

Full templates live in templates/SKILL.md.

The PostToolUse hook (optional)

obsidian-docs hook install

After every Write / Edit / MultiEdit, Claude gets a JSON-injected reminder:

obsidian-docs reminder: you just modified src/auth/index.ts. If this changed a module’s purpose, dependencies, public interface, or introduced a non-obvious gotcha, update the corresponding note in docs/modules/. Skip this if the change was purely cosmetic.

The hook is smart — it skips:

Edits inside docs/ itself (no feedback loop)
*.md, *.json, *.yml, *.yaml, *.toml, *.lock, .env*
node_modules/, .git/, dist/, build/, .next/
Test/spec files (*.test.*, *.spec.*, __tests__/)

Zero dependencies — uses python3 for JSON parsing (ships with macOS/Linux).

Auto-detection

install reads your repo and adapts. Detected automatically:

Layer	Detected from
Language	`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `composer.json`
Framework	Next.js, Remix, React, Vue, Svelte, Express, Fastify, NestJS, Hono, Django, Flask
Database	PostgreSQL, MySQL, MongoDB, Redis, SQLite, Prisma, Drizzle
Package manager	pnpm, yarn, npm, bun

The detected stack is written into your CLAUDE.md so Claude has it as context.

How is this different from…

Tool	What it does	Comparison
Vanilla Obsidian	PKM for humans	You write every note manually, no AI integration
README.md / wiki	Static docs	Goes stale the moment code changes
Graphify	Auto-extracted code graph for AI	Structural — explains what. obsidian-docs is human-curated why. They’re complementary.
JSDoc / docstrings	Inline API docs	Per-function reference, not architecture or decisions
Notion / Confluence	Hosted wiki	Lives outside the repo, no AI hooks, drifts

The unique angle: docs versioned with code, written by Claude, browsable as a graph by humans, queryable as structured context by any AI.

Project structure

obsidian-docs/
├── bin/obsidian-docs           # CLI entry
├── commands/
│   ├── install.js              # scaffold vault + skill, patch CLAUDE.md
│   ├── uninstall.js            # surgical removal
│   ├── hook.js                 # PostToolUse hook install/uninstall
│   ├── backfill.js             # spawn Claude to populate the vault
│   ├── status.js               # health check
│   └── update.js               # refresh SKILL.md
├── lib/
│   ├── detect.js               # stack auto-detection
│   └── claude-md.js            # CLAUDE.md marker-block patcher
├── templates/
│   ├── SKILL.md                # the skill Claude follows
│   └── hooks/nudge.sh          # PostToolUse reminder script
└── test/cli.test.js            # 21 tests, zero deps (node:test)

Development

git clone https://github.com/apoorva-01/obsidian-docs.git
cd obsidian-docs
npm install
npm test                # 21 tests, ~60s
npm link                # use `obsidian-docs` from any directory

Contributing

Issues and PRs welcome at github.com/apoorva-01/obsidian-docs.

If you’re proposing a behavior change, please add a test in test/cli.test.js — the suite uses Node’s built-in node:test so there’s nothing to install.

License

_{Built with Claude Code. The skill maintains itself.}