Skip to content
Khiip Khiip Khiip

Troubleshooting

pip install khiip fails

Khiip isn’t on PyPI yet. Install from source:

Terminal window
git clone https://github.com/KhiipAI/khiip.git ~/projects/khiip
cd ~/projects/khiip
pip install -e ".[dev]"

CLI / plugin can’t reach the daemon (“connection refused”)

The CLI, Obsidian plugin, and MCP server all talk to a running daemon. Start it first:

Terminal window
khiipd serve   # listens on 127.0.0.1:8478 by default

If you changed the host/port ([daemon] host/port in config.toml, or --host/--port), make sure the client points at the same address (KHIIP_DAEMON_URL for the MCP server).

Reddit captures fail or return thin results

Reddit capture is credential-free by default via the old.reddit.com HTML channel, so most failures are transient: Reddit’s WAF is rate-sensitive and can return a temporary 403 to bursty traffic (the extractor already paces + retries). If captures consistently fail, check that old.reddit.com is reachable from your machine — the channel is self-host-only by design (a datacenter IP would be blocked).

Deep comment trees and galleries resolve credential-free (the HTML channel follows old.reddit’s “load more comments” links via /api/morechildren, bounded by a paced request budget). For a 60 req/min headroom on very large threads beyond that budget — plus gallery dimensions/captions the HTML tiles don’t expose — add your own Reddit app (optional) — see Installation → per-source credentials:

[extractors.reddit]
client_id = "your-reddit-client-id"
client_secret = "your-reddit-client-secret"

…or the KHIIP_REDDIT_CLIENT_ID / KHIIP_REDDIT_CLIENT_SECRET env vars. A configured app is tried first; if it’s missing or expired, capture falls back to the HTML channel.

khiip-mcp-server not found by Claude Desktop

When you install with pip install -e inside a venv, the console script lives in that venv’s bin/ — which Claude Desktop’s PATH may not include. Point at the full path:

{
  "mcpServers": {
    "khiip": { "command": "/Users/you/projects/khiip/.venv/bin/khiip-mcp-server" }
  }
}

Also remember the daemon must be running before MCP tool calls land — the MCP server is a thin proxy to it.

Daemon and plugin disagree on which vault/data they use

This is almost always KHIIP_HOME set in your shell rc. macOS GUI apps (Obsidian, Claude Desktop, and the MCP server when launched by Claude Desktop) are started by launchd and do not inherit shell environment variables — so a KHIIP_HOME in .zshrc makes the CLI and the GUI apps point at different workspaces.

Fix: don’t set KHIIP_HOME in your shell rc. It’s a per-invocation knob for tests and demos only (see Configuration).

A media file or YouTube video didn’t download

Media fetching is best-effort and reports its own status independently of extraction (per P-δ failure handling) — a failed media download doesn’t discard a good capture. Some causes:

  • Video preservation is opt-in. Enable it with [media] download_videos = true; it’s off by default.
  • The source video is unavailable (removed/private upstream). Khiip records the failed status; re-attempt later with khiipd refetch <id> --media.

First khiipd serve / recall is slow

The first run fetches the bundled MiniLM-L6 ONNX model (~80MB), one time, over the network. After that, recall runs locally and offline.

Still stuck?