# 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

```bash
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/`):

```bash
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

| File | Purpose |
|---|---|
| `SKILL.md` | Agent-facing instructions. Loaded automatically by the AI runtime. |
| `api-reference.md` | Full endpoint contract (status codes, params, response shapes). |
| `examples.md` | Conversation → API recipe patterns. |
| `README.md` | This file — human setup / install / troubleshooting. |

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.

```bash
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

| Symptom | Cause | Fix |
|---|---|---|
| `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. |
| `Status: port_conflict` in `/health` | Another process on 19828 | `lsof -i :19828` to find the squatter; quit and restart the app. |
| Every endpoint returns 401 | No token configured | Settings → API Server → Generate; OR `export LLM_WIKI_API_TOKEN=...` |
| Every endpoint returns 503 with "disabled" | Kill switch is on | Settings → API Server → check "Enable local HTTP API". |
| Every endpoint returns 503 with "busy" | In-flight cap reached (64 concurrent) | Back off, send fewer parallel requests. |
| 429 on rapid requests | Rate limit: 120 req/sec global | Back off ≥1s. |
| `files/content` returns 415 on `.pdf` | API is text-only | Read source PDFs via the desktop UI; only text-ish extensions are exposed. |
| `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. |

## 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:

```bash
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.