mirror of
https://github.com/Ar9av/obsidian-wiki.git
synced 2026-09-14 20:36:34 +08:00
Arnav
77d74e0261
* feat(config): resolve global config from an XDG-style location (#172) The global config lived at ~/.obsidian-wiki, which isn't XDG-compliant. It now resolves to $XDG_CONFIG_HOME/obsidian-wiki (default ~/.config/obsidian-wiki). Existing installs are unaffected: if ~/.obsidian-wiki is present and the XDG path is not, the legacy directory is used as-is. No migration is required, and nothing moves on upgrade. Once the XDG path exists it wins, so `mv ~/.obsidian-wiki ~/.config/obsidian-wiki` is all a migration takes. Resolution is implemented identically in Python (cli.py), bash (setup.sh, scripts/daily-update.sh, scripts/wiki-notify.sh), and the Config Resolution Protocol that every skill defers to, so vault-scoped state and named `config.<name>` profiles stay in one place. * fix(config): stop setup from wiping user-added config keys `write_config` rewrote the global config with only the three setup-managed keys, so every `obsidian-wiki setup` — including the one a pip upgrade prompts for — silently destroyed anything else in the file: OBSIDIAN_LINK_FORMAT, QMD_WIKI_COLLECTION, WIKI_SKIP_PROJECTS, sync settings, and comments. Setup now owns only OBSIDIAN_VAULT_PATH, OBSIDIAN_WIKI_REPO and OBSIDIAN_WIKI_VERSION, updating those in place and carrying every other line over untouched. Duplicate definitions of a managed key collapse to one. Predates the XDG change (same behavior on main) but is fixed here because this branch already touches config writing, and the XDG work makes re-running setup more likely. Also pins PYTHONPATH in both new test files so they exercise this checkout rather than whatever obsidian_wiki happens to be installed.
130 lines
7.0 KiB
Markdown
130 lines
7.0 KiB
Markdown
# Installation
|
|
|
|
Four ways in. Pick one — they all end at the same place: your vault path in the global config (`~/.config/obsidian-wiki/config`) and the skills discoverable by your agent.
|
|
|
|
> **Upgrading from an older version?** The config directory used to be `~/.obsidian-wiki`. If you already have it, everything keeps working — that path is still honored and nothing needs to move. See [Where the global config lives](configuration.md#where-the-global-config-lives).
|
|
|
|
| Path | Best for | Writes global config | Installs into all agents |
|
|
|---|---|---|---|
|
|
| [pip](#install-via-pip-recommended) | Most people | ✅ | ✅ |
|
|
| [Let your agent do it](#let-your-agent-set-it-up) | No terminal required | ✅ | ✅ |
|
|
| [git clone + `setup.sh`](#install-via-git-clone) | Contributors, hackers | ✅ | ✅ |
|
|
| [Skills CLI](#install-via-skills-cli-deprecated) | Deprecated — partial install | ❌ | ❌ (current agent only) |
|
|
|
|
## Install via pip (recommended)
|
|
|
|
```bash
|
|
pip install obsidian-wiki
|
|
obsidian-wiki setup --vault /path/to/your/digital/brain
|
|
```
|
|
|
|
`obsidian-wiki setup` writes the config to `~/.config/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"**.
|
|
|
|
Useful flags:
|
|
|
|
```bash
|
|
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 `~/.config/obsidian-wiki/config`.
|
|
|
|
Run `obsidian-wiki info` to see the resolved paths and `obsidian-wiki doctor` to health-check the result. See the [CLI reference](cli.md) for everything else the package ships.
|
|
|
|
## Let your agent set it up
|
|
|
|
The fastest path — no commands required. Give your agent this repo and say:
|
|
|
|
```text
|
|
https://github.com/Ar9av/obsidian-wiki — set up my wiki
|
|
```
|
|
|
|
The agent reads [`.skills/wiki-setup/SKILL.md`](../.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. 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 git clone
|
|
|
|
```bash
|
|
git clone https://github.com/Ar9av/obsidian-wiki.git
|
|
cd obsidian-wiki
|
|
bash setup.sh
|
|
```
|
|
|
|
`setup.sh` asks for your vault path, writes the config to `~/.config/obsidian-wiki/config`, symlinks skills into all your agents, and installs `wiki-update`, `wiki-query`, and `wiki-context-pack` globally so you can use them from any project.
|
|
|
|
Open the project in your agent and say **"set up my wiki"**.
|
|
|
|
For local-only config, copy `.env.example` to `.env` and set `OBSIDIAN_VAULT_PATH` — a `.env` in the working directory (or any parent up to `$HOME`) takes precedence over the global config. See [Configuration](configuration.md).
|
|
|
|
### What `setup.sh` wires up
|
|
|
|
1. **Global config** at `~/.config/obsidian-wiki/config` with your vault path and the repo location. This is how skills know where to read and write.
|
|
2. **Portable skills** — `wiki-update`, `wiki-query`, and `wiki-context-pack` symlinked into `~/.claude/skills/` so they're available from any project in Claude Code.
|
|
3. **Global symlinks** for every agent's discovery path:
|
|
- `~/.gemini/skills/` — Gemini CLI (canonical)
|
|
- `~/.gemini/antigravity/skills/` — Google Antigravity (legacy)
|
|
- `~/.codex/skills/` — Codex
|
|
- `~/.hermes/skills/` — Hermes
|
|
- `~/.openclaw/skills/` — OpenClaw (managed)
|
|
- `~/.copilot/skills/` — GitHub Copilot CLI
|
|
- `~/.trae/skills/` + `~/.trae-cn/skills/` — Trae / Trae CN
|
|
- `~/.kiro/skills/` — Kiro CLI
|
|
- `~/.pi/agent/skills/` — Pi
|
|
- `~/.agents/skills/` — OpenCode, Aider, Factory Droid, and other `AGENTS.md`-aware agents
|
|
4. **Project-local symlinks** — `.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`, `.agents/skills/`, `.pi/skills/`, `.kiro/skills/`
|
|
5. **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`
|
|
6. **GitHub sync** (optional) — see [Configuration → Syncing your vault to GitHub](configuration.md#syncing-your-vault-to-github)
|
|
|
|
`obsidian-wiki setup` and `setup.sh` share one implementation, so pip and source installs produce the identical result.
|
|
|
|
## Install via Skills CLI (deprecated)
|
|
|
|
```bash
|
|
npx skills add Ar9av/obsidian-wiki
|
|
```
|
|
|
|
This only installs the markdown skills into the current agent. It does **not** write the global config, configure GitHub sync, 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 pip or git clone instead.
|
|
|
|
Browse the full skill list at [skills.sh/ar9av/obsidian-wiki](https://skills.sh/ar9av/obsidian-wiki).
|
|
|
|
## Open in Obsidian
|
|
|
|
Open your vault directory in Obsidian (File → Open Vault). The wiki pages, wikilinks, and graph view all work natively. Nothing about the vault is proprietary — it's markdown files with YAML frontmatter.
|
|
|
|
## Multiple vaults
|
|
|
|
Keep a default vault active in `~/.config/obsidian-wiki/config`, or create named configs like `~/.config/obsidian-wiki/config.work` with `/wiki-switch new work`.
|
|
|
|
From any directory, route one request to a named vault with `@name`:
|
|
|
|
```text
|
|
@work update wiki
|
|
@research save this
|
|
wiki-query @personal what do I know about MCP security
|
|
```
|
|
|
|
The `@name` override applies **only to that request** and never changes your default vault. To change the default, use `/wiki-switch <name>` — it re-points the active symlink.
|
|
|
|
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. 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.
|
|
|
|
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`).
|
|
|
|
## Verifying the install
|
|
|
|
```bash
|
|
obsidian-wiki doctor
|
|
```
|
|
|
|
`doctor` catches broken setup, stale installs, and malformed vault state. Add `--json` for machine-readable output.
|
|
|
|
## Next steps
|
|
|
|
- [Skills Reference](skills.md) — what you can actually ask for
|
|
- [Configuration](configuration.md) — every config variable, QMD, GitHub sync
|
|
- [Agent Compatibility](agents.md) — per-agent details and manual setup
|