Skip to content

SETUP.md

Latest commit

 

History

History
181 lines (135 loc) · 8.49 KB

SETUP.md

File metadata and controls

181 lines (135 loc) · 8.49 KB
Raw

Setup

A skill-based framework for AI coding agents — Claude Code, Cursor, Windsurf, Pi, Gemini CLI, Google Antigravity, Codex, Hermes, OpenClaw, OpenCode, Aider, Factory Droid, Trae / Trae CN, Kiro, GitHub Copilot (CLI + VS Code Chat) — to build and maintain an Obsidian wiki using Karpathy's LLM Wiki pattern. No scripts, no API keys — the agent is the LLM.

Running bash setup.sh wires up every supported agent: project-local skill symlinks (.claude/skills/, .cursor/skills/, .windsurf/skills/, .agents/skills/, .kiro/skills/), global symlinks (~/.claude/skills/, ~/.gemini/skills/, ~/.codex/skills/, ~/.hermes/skills/, ~/.openclaw/skills/, ~/.copilot/skills/, ~/.trae/skills/, ~/.trae-cn/skills/, ~/.kiro/skills/, ~/.agents/skills/), and always-on rule files (CLAUDE.md, GEMINI.md, AGENTS.md, .hermes.md, .cursor/rules/…, .windsurf/rules/…, .kiro/steering/…, .agent/rules/…, .agent/workflows/…, .github/copilot-instructions.md). See the Agent Compatibility table in README.md for the full matrix.

Install via pip (no clone needed)

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

This does everything setup.sh does without a clone: writes ~/.obsidian-wiki/config and installs every skill into all supported agents' skills directories (symlinked to the installed package, so pip install -U obsidian-wiki upgrades them everywhere). Add --project . to also drop project-local skills and the AGENTS.md / rule files into the current repo, or --copy to copy skill files instead of symlinking. Run obsidian-wiki info to see resolved paths.

Useful local commands after setup:

obsidian-wiki doctor
obsidian-wiki query "what do I know about rate limiting?"
obsidian-wiki lint

The rest of this doc covers the git clone + setup.sh path.

Quick Start (git clone)

1. Set your vault path

cp .env.example .env

Open .env and set OBSIDIAN_VAULT_PATH to your Obsidian vault:

OBSIDIAN_VAULT_PATH=/path/to/your/vault

That's the only required config.

2. Point an agent at the skills

Open this project in your coding agent and tell it what you want:

What you say Skill triggered
"Set up my wiki" wiki-setup
"Ingest my documents from ~/research" wiki-ingest
"/wiki-history-ingest claude" or "/wiki-history-ingest codex" wiki-history-ingest
"Import my Claude history" claude-history-ingest
"Import my Codex history" codex-history-ingest
"Import my Pi history" pi-history-ingest
"Process this ChatGPT export" wiki-ingest
"What's the status of my wiki?" wiki-status
"What do I know about X?" wiki-query
"Audit my wiki" wiki-lint
"Rebuild from scratch" wiki-rebuild

The agent reads the skills from .skills/, resolves the vault path via the Config Resolution Protocol (@name override → .env → ~/.obsidian-wiki/config), and does the work.

3. Open in Obsidian

Open your vault directory in Obsidian (File → Open Vault). The wiki pages, wikilinks, and graph view all work natively.

What Can It Ingest?

Anything text-based:

Source Skill What it reads
Markdown, PDFs, text files wiki-ingest Any document directory
Claude Code history claude-history-ingest ~/.claude/ — conversations, memories, sessions
Codex CLI history codex-history-ingest ~/.codex/ — sessions, rollouts, history index
Pi agent sessions pi-history-ingest ~/.pi/agent/sessions/ — tree-structured JSONL
ChatGPT exports wiki-ingest conversations.json from ChatGPT export
Slack / Discord logs wiki-ingest Channel export JSON files
Meeting transcripts wiki-ingest Any text transcript
Raw text dumps wiki-ingest Anything — CSV, logs, journals, notes

Tracking & Delta

The framework tracks everything it ingests via .manifest.json in the vault root. This enables:

  • Status view — "What's been ingested? What's new? What's changed?"
  • Delta ingestion — Only process new/modified sources, skip what's already in the wiki
  • Provenance — Which source produced which wiki page
  • Staleness detection — Source changed but wiki page hasn't been updated

Typical workflow

"What's the status?"     → wiki-status computes the delta
"Ingest the new stuff"   → wiki-ingest processes only the delta (append mode)
"What's the status now?" → wiki-status confirms everything is up to date

When things drift too far

"Archive and rebuild"    → wiki-rebuild archives current wiki to _archives/, clears, ready for fresh ingest
"Restore the old one"    → wiki-rebuild restores from a previous archive

Archives live at $VAULT/_archives/ with full snapshots. Nothing is ever lost.

Vault Structure

$OBSIDIAN_VAULT_PATH/
├── concepts/           # Global knowledge — ideas, theories, mental models
├── entities/           # People, orgs, tools
├── skills/             # How-to knowledge, procedures
├── references/         # Source summaries
├── synthesis/          # Cross-cutting analysis
├── journal/            # Timestamped logs
├── projects/           # Per-project knowledge
│   ├── my-project/
│   │   ├── _project.md
│   │   ├── concepts/
│   │   └── skills/
│   └── another-project/
│       └── ...
├── _archives/          # Wiki snapshots for rebuild/restore
├── index.md            # Auto-maintained catalog
├── log.md              # Chronological operation log
└── .manifest.json      # Ingest tracking ledger

Knowledge that's project-specific goes under projects/<name>/. Knowledge that's general goes in the global category directories. Both are cross-referenced with [[wikilinks]].

Optional Config

Variable What it does Default
OBSIDIAN_SOURCES_DIR Directories with docs to ingest (comma-separated) (empty — point agent at specific files)
OBSIDIAN_CATEGORIES Wiki page categories concepts,entities,skills,references,synthesis,journal
OBSIDIAN_MAX_PAGES_PER_INGEST Max pages updated per ingest 15
CLAUDE_HISTORY_PATH Where to find Claude data auto-discovers from ~/.claude
CODEX_HISTORY_PATH Where to find Codex data defaults to ~/.codex
PI_HISTORY_PATH Where to find Pi sessions defaults to ~/.pi/agent/sessions
LINT_SCHEDULE Wiki health check frequency weekly

Skills Reference

Skill Purpose
llm-wiki Core pattern — 3-layer architecture, page templates, project org
wiki-setup Initialize vault structure, create index/log, configure Obsidian
wiki-ingest Distill source documents into wiki pages (append or full mode), plus any raw text — chat exports, logs, transcripts, anything
wiki-history-ingest Unified history ingest router (claude, codex, pi)
claude-history-ingest Mine ~/.claude conversations and memories into wiki pages
codex-history-ingest Mine ~/.codex sessions and rollout logs into wiki pages
pi-history-ingest Mine ~/.pi/agent/sessions JSONL history into wiki pages
wiki-status Audit: what's ingested, what's pending, delta, recommend action
wiki-rebuild Archive current wiki, rebuild from scratch, or restore from archive
wiki-query Answer questions from the compiled wiki with citations
wiki-lint Find orphans, broken links, stale content, contradictions
wiki-update Sync current project's knowledge into the vault (works from any project)
skill-creator Create new skills to extend the framework

How It Works

No scripts, no dependencies. The skills are markdown files that tell an AI agent how to operate on your Obsidian vault:

  1. Agent reads .env for vault path
  2. Agent reads .manifest.json to know what's already been done
  3. Agent reads the relevant skill for instructions
  4. Agent uses its built-in tools (read, write, search) to do the work
  5. Agent updates .manifest.json to track what it did
  6. Output is standard Obsidian-compatible markdown with frontmatter and [[wikilinks]]

The wiki is the artifact. The agent is the maintainer. Obsidian is the viewer.

Extending

Want a new workflow? Use the skill-creator skill:

"Create a skill that generates weekly summaries from my journal entries"

It walks you through drafting, testing, and refining a new skill in .skills/.