obsidian-wiki

A digital brain you grow with your AI agent. It remembers what you figure out, connects it to what you already know, and answers when you ask.

The pattern comes from Andrej Karpathy's LLM Wiki gist: compile knowledge once into interconnected markdown files and keep them current, instead of asking an LLM the same questions over and over (or running RAG every time). Obsidian is how you see the brain. Your AI agent is how you grow it.

We built a framework around that idea. Every skill is a markdown file that any AI coding agent (Claude Code, Cursor, Windsurf, Pi, and others) reads and runs. Point it at an Obsidian vault, tell it what to remember, and the vault becomes a second brain you own.

Quick Start

Let your agent set it up

The fastest path — no commands required. Give your agent this repo and say:

https://github.com/Ar9av/obsidian-wiki — set up my wiki

The agent reads .skills/wiki-setup/SKILL.md from the repo, asks where you want your vault to live, and initializes the full structure: directories, index, log, Obsidian config, and an optional auto-capture hook. That's it — the skill is the setup guide.

This works in any agent that can read files (Claude Code, Cursor, Windsurf, Codex, Gemini CLI, Kiro, and more). After setup, every wiki skill is available immediately.

Install via pip (recommended)

pip install obsidian-wiki
obsidian-wiki setup --vault /path/to/your/digital/brain

obsidian-wiki setup writes the config to ~/.obsidian-wiki/config and installs every wiki skill into all your AI agents (Claude Code, Cursor, Codex, Gemini, Hermes, Pi, and more). Skills are symlinked to the installed package, so pip install -U obsidian-wiki upgrades them everywhere — just re-run obsidian-wiki setup to pick up new skills. Then open a project in your agent and say "set up my wiki".

obsidian-wiki list              # list the bundled skills
obsidian-wiki info              # show install paths, version, and config
obsidian-wiki doctor            # health-check config, vault shape, and installed skills
obsidian-wiki query "rate limiting"  # query the configured vault from the terminal
obsidian-wiki lint              # lint the configured vault for broken links / metadata gaps
obsidian-wiki setup --project . # also drop project-local skills + AGENTS.md into the current repo
obsidian-wiki setup --copy      # copy skill files instead of symlinking

OBSIDIAN_VAULT_PATH is just any directory where you want your digital brain to live, a new empty folder or an existing Obsidian vault. Omit --vault to be prompted (or set it later in ~/.obsidian-wiki/config).

Local CLI utilities

The Python package also ships a few local commands for inspection and maintenance:

obsidian-wiki doctor --json
obsidian-wiki query "what do I know about MCP security?"
obsidian-wiki lint --strict
obsidian-wiki graph-query /path/to/vault "transformer architecture"
obsidian-wiki graph-analyse /path/to/vault --pretty

Use doctor to catch broken setup, stale installs, or malformed vault state. Use query and lint when you want fast local answers without going through an agent prompt. The lower-level graph-query, graph-analyse, batch-plan, cache-*, and ast-extract commands are still available for automation and debugging.

Multiple Vaults

Keep a default vault active in ~/.obsidian-wiki/config, or create named configs like ~/.obsidian-wiki/config.work with /wiki-switch new work. From any directory, route one request to a named vault with @name, for example @work update wiki or wiki-query @personal what do I know about MCP security. The @name override applies only to that request and never changes your default vault.

All supported agents can use this syntax after obsidian-wiki setup or setup.sh, because the shared skills and always-on bootstrap files all point back to the same Config Resolution Protocol. The routing token works with write skills (@work update wiki, @research save this) and read skills (wiki-query @personal what do I know about X).

Install via Skills CLI (deprecated)

npx skills add Ar9av/obsidian-wiki

This only installs the markdown skills into the current agent. It does not write ~/.obsidian-wiki/config, install ~/.obsidian-wiki/sync.sh, or wire the global multi-agent bootstrap that obsidian-wiki setup / setup.sh performs.

Use this path only if you intentionally want a partial, agent-local install and are prepared to manage config yourself. For a complete setup, use Install via pip or Install via git clone instead.

Browse the full skill list at skills.sh/ar9av/obsidian-wiki.

Install via git clone

git clone https://github.com/Ar9av/obsidian-wiki.git
cd obsidian-wiki
bash setup.sh

setup.sh asks for your vault (path to your digital brain) path, writes the config to ~/.obsidian-wiki/config, symlinks skills into all your agents, and installs wiki-update globally so you can use it from any project.

Open the project in your agent and say "set up my wiki". That's it.

Agent Compatibility

Works with any AI coding agent that can read files — Claude Code, Cursor, Windsurf, Pi, Codex, Gemini CLI, Kiro, and more. setup.sh handles skill discovery for each one automatically.

Supported agents and manual setup instructions

Agent	Bootstrap	Skills Directory	Slash Commands
Claude Code	CLAUDE.md	.claude/skills/ + ~/.claude/skills/	✅ /wiki-ingest, /wiki-status, etc.
Cursor	.cursor/rules/obsidian-wiki.mdc	.cursor/skills/	✅ /wiki-ingest, /wiki-status, etc.
Windsurf	.windsurf/rules/obsidian-wiki.md	.windsurf/skills/	✅ via Cascade
Codex (OpenAI)	AGENTS.md	~/.codex/skills/	$wiki-ingest (Codex uses $)
Gemini CLI	GEMINI.md	~/.gemini/skills/	✅ /wiki-ingest, /wiki-query, etc.
Google Antigravity	.agent/rules/ + .agent/workflows/	.agents/skills/	✅ via workflows registry
Kiro IDE/CLI	.kiro/steering/obsidian-wiki.md	.kiro/skills/ + ~/.kiro/skills/	✅ /wiki-ingest, /wiki-status, etc.
Hermes	.hermes.md	~/.hermes/skills/	✅ /wiki-history-ingest hermes, etc.
OpenClaw	AGENTS.md	~/.openclaw/skills/ + ~/.agents/skills/	✅ /wiki-ingest, /wiki-history-ingest openclaw, etc.
OpenCode	AGENTS.md	~/.agents/skills/	✅ /wiki-ingest, /wiki-query, etc.
Aider	AGENTS.md	~/.agents/skills/	Describe intent in chat
Factory Droid	AGENTS.md	~/.agents/skills/	✅ /wiki-ingest, /wiki-query, etc.
Trae / Trae CN	AGENTS.md	~/.trae/skills/ / ~/.trae-cn/skills/	✅ via Agent tool
GitHub Copilot (VS Code)	.github/copilot-instructions.md	—	Describe intent in chat
GitHub Copilot (CLI)	—	~/.copilot/skills/	✅ /wiki-ingest, /wiki-query, etc.
Kilocode	AGENTS.md / CLAUDE.md	.agents/skills/ + .claude/skills/	✅ /wiki-ingest, /wiki-status, etc.
Pi	AGENTS.md	.pi/skills/ + ~/.pi/agent/skills/	✅ /wiki-ingest, /wiki-history-ingest pi, etc.

Each agent has its own convention for discovering skills. setup.sh symlinks the canonical .skills/ directory into each agent's expected location. You write skills once, every agent can use them. The same is true for named-vault routing: @name is documented in the shared skills and bootstrap context, so Claude Code, Cursor, Windsurf, Codex, Gemini, Kiro, Hermes, OpenClaw, Copilot CLI, Pi, and the generic AGENTS.md agents all pick it up from the same instructions.

Manual setup (if you prefer setup.sh)

Claude Code

Skills are auto-discovered from .claude/skills/. Either run setup.sh or copy .skills/* to .claude/skills/. The CLAUDE.md file at the repo root is automatically loaded as project context.

cd /path/to/obsidian-wiki && claude "set up my wiki"

Cursor

Skills are auto-discovered from .cursor/skills/. The .cursor/rules/obsidian-wiki.mdc file provides always-on context. Either run setup.sh or copy .skills/* to .cursor/skills/. Then type /wiki-setup in the chat.

Windsurf

Cascade reads rules from .windsurf/rules/ and skills from .windsurf/skills/. Either run setup.sh or copy .skills/* to .windsurf/skills/. Then tell Cascade: "set up my wiki".

Codex

Reads AGENTS.md for project context. setup.sh installs skills globally to ~/.codex/skills/. Either run setup.sh or manually symlink .skills/* to ~/.codex/skills/.

cd /path/to/obsidian-wiki && codex "set up my wiki"

Gemini CLI

Reads GEMINI.md and discovers global skills from ~/.gemini/skills/. Either run setup.sh or manually symlink .skills/* to ~/.gemini/skills/.

cd /path/to/obsidian-wiki && gemini "set up my wiki"

Google Antigravity

Always-on via .agent/rules/ + .agent/workflows/. setup.sh ships both files and symlinks skills into .agents/skills/. The legacy ~/.gemini/antigravity/skills/ path is also wired.

Kiro IDE/CLI

Always-on via .kiro/steering/*.md with inclusion: always. setup.sh symlinks .skills/* into both .kiro/skills/ and ~/.kiro/skills/. Invoke with /wiki-ingest, /wiki-query, etc.

OpenCode / Aider / Factory Droid / Trae

All read AGENTS.md at the repo root. setup.sh symlinks skills into ~/.agents/skills/ (shared discovery path). Trae also gets ~/.trae/skills/ and ~/.trae-cn/skills/.

Hermes

Reads .hermes.md first, then falls back to AGENTS.md. Skills discovered from ~/.hermes/skills/. Run setup.sh or manually symlink .skills/* there.

cd /path/to/obsidian-wiki && hermes "set up my wiki"
# Mine Hermes history into the wiki:
/wiki-history-ingest hermes

OpenClaw

Reads AGENTS.md (priority 10). Discovers skills from ~/.openclaw/skills/ and ~/.agents/skills/. Skills auto-register as slash commands.

cd /path/to/obsidian-wiki && openclaw "set up my wiki"
# Mine OpenClaw history:
/wiki-history-ingest openclaw

GitHub Copilot

VS Code Chat: reads .github/copilot-instructions.md. Say "set up my wiki" in Copilot Chat.

CLI: discovers skills from ~/.copilot/skills/. Run setup.sh or manually symlink .skills/* there.

Pi

Reads AGENTS.md (walking up from cwd). Discovers skills from .pi/skills/, .agents/skills/, and ~/.pi/agent/skills/. Run setup.sh or manually symlink .skills/* to ~/.pi/agent/skills/.

cd /path/to/obsidian-wiki && pi "set up my wiki"
# Mine Pi session history:
/wiki-history-ingest pi

How it works

Every time you feed the brain, it runs through four stages:

1. Ingest — The agent reads your source material directly. It handles whatever you throw at it: markdown files, PDFs (with page ranges), JSONL conversation exports, plain text logs, chat exports, meeting transcripts, and images (screenshots, whiteboard photos, diagrams — vision-capable model required). No preprocessing step, no pipeline to run. The agent reads the file the same way it reads code.

2. Pull Information — From the raw source, the agent pulls out concepts, entities, claims, relationships, and open questions. A conversation about debugging a React hook yields a "stale closure" pattern. A research paper yields the key idea and its caveats. A work log yields decisions and their rationale. Noise gets dropped, signal gets kept. Each page also gets a 1–2 sentence summary: in its frontmatter at write time — later queries use this to preview pages without opening them.

3. Merge — New knowledge gets merged against what's already in the wiki. If a concept page exists, the agent updates it — merging new information, noting contradictions, strengthening cross-references. If it's genuinely new, a page gets created. Nothing is duplicated. Sources are tracked in frontmatter so every claim stays attributable.

4. Schema — The wiki schema isn't fixed upfront. It emerges from your sources and evolves as you add more. The agent maintains coherence: categories stay consistent, wikilinks point to real pages, the index reflects what's actually there. When you add a new domain (a new project, a new field of study), the sche