nashsu/llm_wiki_skill

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.

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.

Installation

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 this skill enables

• "What does my wiki say about X?" → hybrid search (keyword + vector) + read
• "Show me the neighborhood of node Y in my graph" → wikilinks traversal
• "Read me the page about Z" → file content fetch
• "I just added new docs, re-index" → backend rescan
• "Give me a structural overview of my wiki" → file tree + index.md

All read-only except sources/rescan (triggers an internal queue diff).

Files

No scripts, no wrappers. If you find yourself wanting one, just curl.

Prerequisites

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.

2. API server enabled. Default: on. Verify in Settings → API Server → "Enable local HTTP API" is checked.

3. Token configured. Default: off (token field empty → every endpoint returns 401). Either:

   • In the app: Settings → API Server → Generate new token. Copy and stash it.
   • Via env: export LLM_WIKI_API_TOKEN=... (overrides UI; persists for the agent process).

   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.

Quick smoke test

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.

export LLM_WIKI_API_TOKEN=...

# 1. Probe — no auth needed
curl -s http://127.0.0.1:19828/api/v1/health

# Expected:
# {
#   "ok": true,
#   "status": "running",
#   "enabled": true,
#   "authConfigured": true,
#   "tokenSource": "env",
#   "allowUnauthenticated": false,
#   ...
# }

# 2. List projects
curl -s -H "Authorization: Bearer $LLM_WIKI_API_TOKEN" \
  http://127.0.0.1:19828/api/v1/projects

# 3. Search the active project
curl -s -H "Authorization: Bearer $LLM_WIKI_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query":"rope","topK":3}' \
  http://127.0.0.1:19828/api/v1/projects/current/search

# 4. Read a page
curl -s -H "Authorization: Bearer $LLM_WIKI_API_TOKEN" \
  "http://127.0.0.1:19828/api/v1/projects/current/files/content?path=wiki/concepts/rope.md"

Add | jq at the end of any of these if you have jq installed and want pretty output. Not required.

Troubleshooting

Security model

• The API listens on 127.0.0.1 only. It is not reachable from other hosts on your network.
• Token-based auth is constant-time compared (no timing leak in the auth check).
• Path traversal blocked at the route handler (safe_join with canonical-path prefix check).
• File reads restricted to a whitelist (purpose.md, schema.md, wiki/**, raw/sources/**); text extensions only; 2 MB cap.
• Body limit 1 MB; in-flight cap 64; rate limit 120/sec.
• No write endpoints in v1. /sources/rescan is the only mutation, and it only reads disk + queues internal work.

What's not in the threat model:

• A malicious local process with the token can read everything in your active project's wiki + sources. Treat the token as a local secret.
• A malicious local process can probe /health (no auth) to discover the API exists. Information disclosure, no content leak.
• 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.

Version

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.

Updating

If you installed via npx skills add, re-run the same command to pull the latest revision:

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

If you cloned the repo, git pull inside the cloned folder is enough — the symlink picks up changes automatically.

Contributing

Source repo: https://github.com/nashsu/llm_wiki_skill

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.

License

See the repository for license details.