obsidian-wiki/SETUP.md

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.

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"	data-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/, reads .env for your vault path, 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	data-ingest	conversations.json from ChatGPT export
Slack / Discord logs	data-ingest	Channel export JSON files
Meeting transcripts	data-ingest	Any text transcript
Raw text dumps	data-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_BUSINESS_FACTS_DB	Optional path for structured business facts such as Kingdee orders	<vault>/_meta/business-facts.sqlite
.runtime/kingdee.env	Private local Kingdee sales-order API config created by scripts/obsidian-wiki-ops.py kingdee config	official sales-order URL, blank credentials
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)
wiki-history-ingest	Unified history ingest router (claude, codex, pi)
data-ingest	Ingest any raw text — chat exports, logs, transcripts, anything
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

Business Facts

Use the business fact database for exact operational questions, for example monthly order counts or sales amounts. Do not ingest every order line into the wiki. Ask normal questions through wiki-query; it will decide when to use structured business facts.

scripts/obsidian-wiki-ops.py kingdee sync --input ./kingdee-orders.json

scripts/obsidian-wiki-ops.py kingdee config
# Fill .runtime/kingdee.env, then test login/refresh without syncing orders:
scripts/obsidian-wiki-ops.py kingdee auth-test

scripts/obsidian-wiki-ops.py kingdee sync \
  --start-bizdate 2026-06-01 \
  --end-bizdate 2026-06-30 \
  --billstatus C
scripts/obsidian-wiki-ops.py kingdee sync --incremental

scripts/obsidian-wiki-ops.py kingdee schema --json
scripts/obsidian-wiki-ops.py kingdee template order_count --vault /path/to/vault --year 2026 --month 6 --json
scripts/obsidian-wiki-ops.py kingdee template sales_amount --vault /path/to/vault --year 2026 --month 6 --json
scripts/obsidian-wiki-ops.py kingdee template staff_order_list --vault /path/to/vault --start-date 2026-06-30 --end-date 2026-07-07 --staff 徐丽 --json
scripts/obsidian-wiki-ops.py kingdee sql "SELECT COUNT(*) AS order_count FROM orders"

scripts/obsidian-wiki-ops.py timer install --vault /path/to/vault

Without --input, the Kingdee sync command creates/reads .runtime/kingdee.env, obtains or refreshes an access token, calls the official sales order query API, then stores the fetched JSON response in <vault>/_meta/business-facts.sqlite. The private config supports configurable login/token URL, request body, response field paths, refresh URL/body, and required x-acgw-identity; fetched tokens are cached in .runtime/kingdee-token.json. .runtime/ is ignored by git.

The answer reports the statistic, counting basis, data source, and last successful sync time. If the latest successful sync is before today, the answer warns that newer data may be missing. wiki-query loads the business schema, chooses a template when one fits, and uses guarded read-only SQL only for gaps. Salesperson templates default to the main salesperson and use --staff-role-scope all to include sales 2/3/4 and follow-up roles. The Linux timer uses systemd --user, runs daily by default, and syncs incrementally with a 48-hour lookback.

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/.