Skip to content
Back to search

llm_wiki_skill

Lets an AI agent (Claude Code, Codex, etc.) query the user's locally-running LLM Wiki desktop app over its built-in HTTP API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nashsu--llm-wiki-skill/badge.svg)](/listings/nashsu--llm-wiki-skill)

HTML

<a href="/listings/nashsu--llm-wiki-skill"><img src="/api/listings/nashsu--llm-wiki-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Recommended — one-liner via `skills` CLI

npx skills add https://github.com/nashsu/llm_wiki_skill.git --skill llm-wiki

This fetches the latest version of the skill from GitHub and registers it with your agent runtime. Re-run the same command to update to a newer revision later.

Alternative — clone + symlink (Claude Code)

If you prefer to manage the source locally and link it into Claude Code (skills live at `~/.claude/skills/`):

git clone https://github.com/nashsu/llm_wiki_skill.git
ln -s "$(pwd)/llm_wiki_skill" ~/.claude/skills/llm-wiki

Alternative — manual drop-in

The skill is three markdown files and nothing else. Drop the folder anywhere your agent runtime discovers skills (e.g. Codex `agents/`, custom MCP server skill dir). No dependencies, no build step.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 205 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: llm-wiki
  3. description: "Query the user's LLM Wiki knowledge base (the LLM Wiki desktop app at 127.0.0.1:19828 — NOT Obsidian, Notion, Apple Notes, Logseq, or any other PKM tool). Trigger ONLY when the user explicitly names LLM Wiki, says 'my wiki', 'my 知识库 / 知识库 / knowledge base', or asks things like 'what does my wiki say about X', 'read wiki page Y', 'show my wiki graph / 知识图谱', 'search in my LLM Wiki project', 'rescan my wiki sources / 重新索引', or names a wiki project by ID. DO NOT trigger on generic 'search my notes', 'find in my notebook', 'check my Obsidian', etc. — those belong to other tools the user may have installed. Covers wiki page search, file listing, content read, knowledge graph navigation, and source rescan against the running LLM Wiki desktop app. Read-only except for source rescan."
  4. ---
  5. # LLM Wiki Local API Skill
  6. Talk to the user's locally-running LLM Wiki app over its built-in HTTP API. This is a **standard JSON API** — call it directly with whatever HTTP tool is already in your environment (`curl`, `fetch`, `requests`, `http` middleware, etc.). No client library to install, no SDK to learn.
  7. Treat the wiki as a **private, structured knowledge base** the user has been curating: pages live as `wiki/**.md`, raw documents under `raw/sources/`, wikilinks form a graph.
  8. ## When to invoke
  9. Invoke **only** when the user is clearly referring to **LLM Wiki** specifically — by app name, by `wiki` framing, or by `知识库` framing. Concretely:
  10. - asks a question framed as "what does my **wiki** / my **knowledge base** / 我的**知识库** / **LLM Wiki** say about X"
  11. - asks to "search **my wiki** / **LLM Wiki** project / 我的**知识库** for X"
  12. - references a **wiki page** by stem / title and wants to read or cross-link
  13. - asks for the **wiki graph / 知识图谱 / wiki overview / wiki structure**
  14. - has just added or edited files under the LLM Wiki **source folder** and wants ingest re-run / **重新索引**
  15. - says "use **my wiki** for context" / "ground your answer in **my wiki**" / "check **my LLM Wiki**"
  16. - names a wiki project (by ID, by absolute path, or by `current`)
  17. **Do NOT invoke when the user says:**
  18. - "search **my notes**" without further qualification — likely Obsidian / Apple Notes / Notion / Logseq / Bear / etc.
  19. - "find in **my notebook**" — likely Jupyter / OneNote / Notability
  20. - "check **my Obsidian / Notion / Roam / Logseq vault**" — explicitly a different tool
  21. - "look up **my Anki / Readwise / Pocket**" — different tool
  22. - "search **my files / my Documents folder**" — generic filesystem, not the wiki
  23. - general world knowledge, current events, or anything the user clearly wants from the open web
  24. When in doubt about which knowledge tool the user means, ask: *"Do you mean your LLM Wiki specifically, or another tool?"* — don't silently call the LLM Wiki API on what might be an Obsidian vault.
  25. ## Quick start
  26. The whole API is plain HTTP + JSON. The fastest path:
  27. ```bash
  28. BASE=http://127.0.0.1:19828
  29. TOKEN="${LLM_WIKI_API_TOKEN:-<paste-from-Settings>}"
  30. # 1. probe state — no auth needed
  31. curl -s $BASE/api/v1/health
  32. # 2. list projects
  33. curl -s -H "Authorization: Bearer $TOKEN" $BASE/api/v1/projects
  34. # 3. search
  35. curl -s -H "Authorization: Bearer $TOKEN" \
  36. -H 'Content-Type: application/json' \
  37. -d '{"query":"rope embedding","topK":5}' \
  38. $BASE/api/v1/projects/current/search
  39. # 4. read a page
  40. curl -s -H "Authorization: Bearer $TOKEN" \
  41. "$BASE/api/v1/projects/current/files/content?path=wiki/concepts/rope.md"
  42. ```
  43. If you're writing TypeScript / JavaScript:
  44. ```ts
  45. const res = await fetch("http://127.0.0.1:19828/api/v1/projects/current/search", {
  46. method: "POST",
  47. headers: { "Authorization": `Bearer ${process.env.LLM_WIKI_API_TOKEN}`, "Content-Type": "application/json" },
  48. body: JSON.stringify({ query: "rope embedding", topK: 5 }),
  49. })
  50. const { results } = await res.json()
  51. ```
  52. Python is the same shape — `urllib.request`, `requests`, `httpx`, whatever you already have. **Don't install anything new.**
  53. ## Auth model
  54. The API is **localhost-only**. The token is one of:
  55. 1. `LLM_WIKI_API_TOKEN` environment variable (if set, overrides UI)
  56. 2. The user's `apiConfig.token` saved via Settings → API Server
  57. 3. `allowUnauthenticated: true` mode (no token needed; rare, user opt-in only)
  58. Always check `/api/v1/health` first — it returns `{ enabled, authConfigured, allowUnauthenticated, tokenSource }`. **If `authConfigured: false && allowUnauthenticated: false`, ask the user to open `Settings → API Server → Generate new token`**. Do not proceed without auth being set up.
  59. Three equivalent ways to send the token:
  60. ```
  61. Authorization: Bearer <token> # preferred
  62. X-LLM-Wiki-Token: <token> # alternative header
  63. ?token=<urlencoded-token> # query param — last resort, leaks into logs
  64. ```
  65. **Never log or echo the token. Never put it in any URL the user can see in your output** (Referer / shell history / logs all leak it).
  66. ## Standard workflow
  67. When the user asks "look it up in my wiki":
  68. 1. **Resolve project** (see [Project resolution](#project-resolution) below).
  69. 2. **Search**: `POST /api/v1/projects/{id}/search` with `{ query, topK: 5..10 }` → ranked hits (`path`, `title`, `snippet`, `score`, `titleMatch`, optional `vectorScore`, `images`). Inspect `response.mode` to know whether hybrid retrieval kicked in.
  70. 3. **Read top hits**: for each promising hit, `GET /api/v1/projects/{id}/files/content?path=...` for the full markdown. Or pass `includeContent: true` to the search to avoid the round-trip.
  71. 4. **Cite + answer**: synthesize an answer grounded in the read pages. **Quote the `path` of each page you used** so the user can verify and jump in-app.
  72. ### Reading the score
  73. The `score` field's scale depends on `mode`:
  74. - **`mode: "keyword"`** — additive keyword score. Filename-exact hits are ~200; phrase-in-title ~50+; bag-of-tokens lands in single digits. Treat anything below ~5% of the top result as low-confidence.
  75. - **`mode: "hybrid"` or `"vector"`** — RRF (Reciprocal Rank Fusion) score, typically in the **0.015–0.035** range. The absolute number is small; relative ordering is what matters. Use the per-result `vectorScore` (raw cosine 0–1) for "how strongly did the embedding match" if you need it.
  76. Don't apply a fixed score threshold across modes. Sort by `score` descending and rely on relative gaps.
  77. ### Project resolution
  78. `{id}` in every project-scoped endpoint accepts **four forms**:
  79. | Form | When to use | Example |
  80. |---|---|---|
  81. | `current` (literal) | Default for "my wiki / 我的知识库 / this project / this wiki". The user is referring to whatever is open in the desktop UI. | `/api/v1/projects/current/search` |
  82. | UUID | The user pasted a project ID, OR you previously resolved a name to an ID and want to re-use it. | `/api/v1/projects/a0e90b29-fcf3-4364-9502-8bd1272de820/files` |
  83. | Absolute filesystem path (URL-encoded) | The user named the path (e.g. `~/notes/research`). Useful when the user has multiple projects with similar names. | `/api/v1/projects/%2FUsers%2Fme%2Fwiki%2Fresearch/files` |
  84. | Project name | **Not supported directly.** You must `GET /api/v1/projects` first, find a match by `name`, then use that project's `id`. |
  85. **Decision tree** for what the user said:
  86. ```
  87. "my wiki" / "my 知识库" / "this wiki" / "this project" / unspecified
  88. → use `current`
  89. "my Research project" / "in Reading"
  90. → GET /api/v1/projects
  91. → name-match (case-insensitive substring on `name`)
  92. → use the resulting `id`
  93. → if 0 matches: tell the user, list available names, fall back to `current` only if they confirm
  94. → if 2+ matches: ask the user to disambiguate, quoting both names + paths
  95. "the project at /Users/me/foo"
  96. → URL-encode the path, use directly
  97. → if the API returns 404, the project isn't registered — list and let user pick
  98. "project a0e90b29-…"
  99. → use the UUID literally
  100. ```
  101. Cache the resolved `id` for the rest of the conversation — there's no need to re-`GET /projects` for every call. But if the user switches contexts mid-conversation ("now look in my Reading project"), re-resolve.
  102. When the user is silent about which project, **default to `current`** and mention it once: *"Looking in your active project (Research Notes)…"*. This avoids cross-project surprises.
  103. For graph / cross-reference questions:
  104. - `GET /api/v1/projects/{id}/graph?limit=200` → `{ nodes: [{id, label, nodeType, path, linkCount}], edges: [{source, target, weight}] }`
  105. - Filter via `?q=term` (substring of id/label, case-insensitive) and `?nodeType=entity|concept|...`
  106. For "I added new docs" requests:
  107. - `POST /api/v1/projects/{id}/sources/rescan` → returns `{ queue: { tasks }, changedTasks: [...] }`. Tell the user how many files changed. Actual ingest runs asynchronously via the desktop queue.
  108. ## Endpoint contract (v1)
  109. | Method | Path | Notes |
  110. |---|---|---|
  111. | GET | `/api/v1/health` | No auth. Returns `{ ok, status, version, enabled, authRequired, authConfigured, allowUnauthenticated, tokenSource }`. |
  112. | GET | `/api/v1/projects` | List projects. Each: `{ id, name, path, current }`. |
  113. | GET | `/api/v1/projects/{id}/files?root=wiki\|sources\|all&recursive=true&maxFiles=2000` | Tree of `{ name, path, isDir, size, children }`. Capped at 10000 nodes (413). |
  114. | GET | `/api/v1/projects/{id}/files/content?path=wiki/foo.md` | Text files only (md/mdx/txt/json/yaml/yml/csv/html/htm/xml/rtf/log). 2 MB max. 415 on binary, 413 on oversize, 403 on out-of-scope path. |
  115. | POST | `/api/v1/projects/{id}/search` | Body: `{ "query": "...", "topK": 10, "includeContent": false }`. **Hybrid (keyword + vector)** when the user has embeddings configured in Settings; falls back to keyword-only otherwise. Response carries `mode: "keyword" \| "vector" \| "hybrid"`, plus `tokenHits` / `vectorHits` and per-result `vectorScore`. Empty query → 400. |
  116. | GET | `/api/v1/projects/{id}/graph?q=&nodeType=&limit=200` | Wikilinks graph from `wiki/*.md`. Limit clamped to 1000. |
  117. | POST | `/api/v1/projects/{id}/sources/rescan` | Triggers a backend rescan using the user's Source Watch config. Returns post-rescan queue + actually-changed tasks. |
  118. | POST | `/api/v1/projects/{id}/chat` | **501** — not implemented in v1. Don't call. |
  119. `{id}` accepts a UUID, an absolute filesystem path (URL-encoded), or the literal string `current`.
  120. ## Error handling
  121. Always treat the status code as the contract:
  122. | Status | Meaning | What to do |
  123. |---|---|---|
  124. | 200 | OK | Use `body.ok === true` belt-and-suspenders; payload is in the same object. |
  125. | 400 | Bad request | Show `body.error`. Typical: empty `query`, invalid `?root=`, oversized body. |
  126. | 401 | Unauthorized | Token missing/wrong. Tell user to set/regenerate in Settings → API Server. |
  127. | 403 | Forbidden | Path traversal or out-of-scope (e.g. `../app-state.json`). Don't retry the same path. |
  128. | 404 | Not found | Unknown project id or unknown route. On unknown project, list projects first to recover. |
  129. | 405 | Method not allowed | Wrong HTTP verb. |
  130. | 413 | Payload too large | File > 2 MB, file tree > maxFiles, or request body > 1 MB. Suggest narrower scope. |
  131. | 415 | Unsupported media | Binary or non-UTF-8 file content. API is text-only. |
  132. | 429 | Too many requests | Rate limit (120 req/sec global). Back off ≥1 second. |
  133. | 500 | Internal error | Log + report; don't loop. |
  134. | 501 | Not implemented | `/chat` stub. Don't retry. |
  135. | 503 | Service unavailable | Two flavors: API toggled off (`error` contains "disabled"); in-flight cap (64) reached ("busy"). Back off ≥2s. |
  136. If the HTTP call itself fails (connection refused / ENOTFOUND): the desktop app is **not running**. Tell the user: "Launch LLM Wiki, then re-try."
  137. ## Etiquette
  138. - **Cite paths.** When you answer using wiki content, name the page: `(from wiki/concepts/rope.md)`. The user uses these to verify and to jump in-app.
  139. - **Stay read-only by default.** Only `sources/rescan` mutates state; everything else is reads. Don't invent write endpoints — they don't exist in v1.
  140. - **Don't dump full pages unless asked.** Snippet + path is usually enough. Pull full content only when reasoning genuinely needs it.
  141. - **Respect the project boundary.** The current project is the user's active context. Do not silently switch projects.
  142. - **Honor the rate limit.** 120 req/sec is plenty for sequential work, but parallel page reads can burst close to it. Batch where the API allows (`includeContent: true` on search avoids N+1 reads).
  143. - **Never leak the token.** Headers are safe; query params and your own output text are not.
  144. ## See also
  145. - `api-reference.md` — full endpoint shapes with request / response examples
  146. - `examples.md` — common conversational patterns mapped to direct `curl` / `fetch` sequences
  147. - `README.md` — human setup notes (token generation, port conflicts, troubleshooting)
README.md · README · 151 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # llm-wiki skill
  2. Lets an AI agent (Claude Code, Codex, etc.) query the user's locally-running **LLM Wiki** desktop app over its built-in HTTP API.
  3. This skill is **documentation only**. The API is a standard HTTP+JSON contract — call it with `curl`, `fetch`, `requests`, or whatever HTTP tool your environment already has. There is no client library, no SDK, no compile step.
  4. ## Installation
  5. ### Recommended — one-liner via `skills` CLI
  6. ```bash
  7. npx skills add https://github.com/nashsu/llm_wiki_skill.git --skill llm-wiki
  8. ```
  9. This fetches the latest version of the skill from GitHub and registers it with your agent runtime. Re-run the same command to update to a newer revision later.
  10. ### Alternative — clone + symlink (Claude Code)
  11. If you prefer to manage the source locally and link it into Claude Code (skills live at `~/.claude/skills/`):
  12. ```bash
  13. git clone https://github.com/nashsu/llm_wiki_skill.git
  14. ln -s "$(pwd)/llm_wiki_skill" ~/.claude/skills/llm-wiki
  15. ```
  16. ### Alternative — manual drop-in
  17. The skill is three markdown files and nothing else. Drop the folder anywhere your agent runtime discovers skills (e.g. Codex `agents/`, custom MCP server skill dir). No dependencies, no build step.
  18. ## What this skill enables
  19. - "What does my wiki say about X?" → hybrid search (keyword + vector) + read
  20. - "Show me the neighborhood of node Y in my graph" → wikilinks traversal
  21. - "Read me the page about Z" → file content fetch
  22. - "I just added new docs, re-index" → backend rescan
  23. - "Give me a structural overview of my wiki" → file tree + index.md
  24. All read-only except `sources/rescan` (triggers an internal queue diff).
  25. ## Files
  26. | File | Purpose |
  27. |---|---|
  28. | `SKILL.md` | Agent-facing instructions. Loaded automatically by the AI runtime. |
  29. | `api-reference.md` | Full endpoint contract (status codes, params, response shapes). |
  30. | `examples.md` | Conversation → API recipe patterns. |
  31. | `README.md` | This file — human setup / install / troubleshooting. |
  32. No scripts, no wrappers. If you find yourself wanting one, just `curl`.
  33. ## Prerequisites
  34. 1. **LLM Wiki desktop app installed and running.** The API binds to `127.0.0.1:19828` only while the app is open. If the app isn't running, the agent will see `connection refused` and tell you.
  35. 2. **API server enabled.** Default: on. Verify in `Settings → API Server → "Enable local HTTP API"` is checked.
  36. 3. **Token configured.** Default: off (token field empty → every endpoint returns 401). Either:
  37. - In the app: `Settings → API Server → Generate new token`. Copy and stash it.
  38. - Via env: `export LLM_WIKI_API_TOKEN=...` (overrides UI; persists for the agent process).
  39. You can also flip `Settings → API Server → "Allow access without a token"`, which removes auth entirely. **Local-only — but any process on this machine can then read your wiki.** Use only with trusted setups.
  40. ## Quick smoke test
  41. > **Windows users**: replace `export LLM_WIKI_API_TOKEN=...` with `$env:LLM_WIKI_API_TOKEN = "..."` (PowerShell) or `set LLM_WIKI_API_TOKEN=...` (cmd.exe). Use `curl.exe` instead of `curl` in PowerShell to bypass the `Invoke-WebRequest` alias. Backslash line-continuations (`\`) become backticks (`` ` ``) in PowerShell and `^` in cmd.
  42. ```bash
  43. export LLM_WIKI_API_TOKEN=...
  44. # 1. Probe — no auth needed
  45. curl -s http://127.0.0.1:19828/api/v1/health
  46. # Expected:
  47. # {
  48. # "ok": true,
  49. # "status": "running",
  50. # "enabled": true,
  51. # "authConfigured": true,
  52. # "tokenSource": "env",
  53. # "allowUnauthenticated": false,
  54. # ...
  55. # }
  56. # 2. List projects
  57. curl -s -H "Authorization: Bearer $LLM_WIKI_API_TOKEN" \
  58. http://127.0.0.1:19828/api/v1/projects
  59. # 3. Search the active project
  60. curl -s -H "Authorization: Bearer $LLM_WIKI_API_TOKEN" \
  61. -H 'Content-Type: application/json' \
  62. -d '{"query":"rope","topK":3}' \
  63. http://127.0.0.1:19828/api/v1/projects/current/search
  64. # 4. Read a page
  65. curl -s -H "Authorization: Bearer $LLM_WIKI_API_TOKEN" \
  66. "http://127.0.0.1:19828/api/v1/projects/current/files/content?path=wiki/concepts/rope.md"
  67. ```
  68. Add `| jq` at the end of any of these if you have `jq` installed and want pretty output. Not required.
  69. ## Troubleshooting
  70. | Symptom | Cause | Fix |
  71. |---|---|---|
  72. | `curl: (7) Failed to connect to 127.0.0.1 port 19828` | App not running | Launch LLM Wiki desktop, wait ~2s for the API server to bind. |
  73. | `Status: port_conflict` in `/health` | Another process on 19828 | `lsof -i :19828` to find the squatter; quit and restart the app. |
  74. | Every endpoint returns 401 | No token configured | Settings → API Server → Generate; OR `export LLM_WIKI_API_TOKEN=...` |
  75. | Every endpoint returns 503 with "disabled" | Kill switch is on | Settings → API Server → check "Enable local HTTP API". |
  76. | Every endpoint returns 503 with "busy" | In-flight cap reached (64 concurrent) | Back off, send fewer parallel requests. |
  77. | 429 on rapid requests | Rate limit: 120 req/sec global | Back off ≥1s. |
  78. | `files/content` returns 415 on `.pdf` | API is text-only | Read source PDFs via the desktop UI; only text-ish extensions are exposed. |
  79. | `tokenSource: "env"` even though I cleared it from UI | `LLM_WIKI_API_TOKEN` env var is set somewhere | `unset LLM_WIKI_API_TOKEN`; or set its value to match what's in your UI. |
  80. ## Security model
  81. - The API listens on `127.0.0.1` only. It is **not reachable from other hosts** on your network.
  82. - Token-based auth is constant-time compared (no timing leak in the auth check).
  83. - Path traversal blocked at the route handler (`safe_join` with canonical-path prefix check).
  84. - File reads restricted to a whitelist (`purpose.md`, `schema.md`, `wiki/**`, `raw/sources/**`); text extensions only; 2 MB cap.
  85. - Body limit 1 MB; in-flight cap 64; rate limit 120/sec.
  86. - No write endpoints in v1. `/sources/rescan` is the only mutation, and it only reads disk + queues internal work.
  87. What's **not** in the threat model:
  88. - A malicious **local** process with the token can read everything in your active project's wiki + sources. Treat the token as a local secret.
  89. - A malicious local process can probe `/health` (no auth) to discover the API exists. Information disclosure, no content leak.
  90. - Cross-origin browser pages can hit the API only if they have the token. Default CORS is `*` — relies on token secrecy. Don't paste your token into untrusted web tools.
  91. ## Version
  92. This skill matches **LLM Wiki API v1** as shipped in app version `0.4.10+`. Hybrid retrieval (keyword + vector) is live; the response carries `mode: "keyword" | "vector" | "hybrid"`, `tokenHits`, `vectorHits`, and per-result `vectorScore`. If the desktop app's `/health` reports a major version bump, check `api-reference.md` for drift before relying on the contract verbatim.
  93. ## Updating
  94. If you installed via `npx skills add`, re-run the same command to pull the latest revision:
  95. ```bash
  96. npx skills add https://github.com/nashsu/llm_wiki_skill.git --skill llm_wiki_skill
  97. ```
  98. If you cloned the repo, `git pull` inside the cloned folder is enough — the symlink picks up changes automatically.
  99. ## Contributing
  100. Source repo: <https://github.com/nashsu/llm_wiki_skill>
  101. Issues and PRs welcome. The skill should stay **client-less** — no scripts, no SDK shim, no wrapper binaries. The whole point of the underlying API is that any HTTP tool can call it; this skill is the contract documentation, not a runtime.
  102. ## License
  103. See the repository for license details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.