whoami.wiki

Common issues and how to fix them.

Wiki not starting

Symptom: wai auth status shows the wiki as offline, or http://localhost:8080 is unreachable.

Fix: Make sure Docker is running, then restart the wiki from the desktop app or by restarting the Docker container directly:

docker restart whoami-wiki

If the port is already in use, you can change it in ~/.whoami/config.json:

{ "wiki": { "port": 8081 } }

Then restart the wiki for the change to take effect.

Symptom: Running wai returns "command not found."

Fix: The desktop app installer should add wai to your PATH automatically. If it didn't, add it manually:

# macOS / Linux
export PATH="$HOME/.whoami/bin:$PATH"

Add this line to your shell profile (~/.zshrc, ~/.bashrc) to make it permanent.

Symptom: The agent can't find whoami.wiki tools or returns connection errors when trying to use them.

Fix: Verify the CLI can reach the wiki:

wai auth status

If the plugin is installed but not detected, try removing and re-adding it:

claude plugin remove whoami
claude plugin add whoami

Make sure you restart your agent session after reinstalling the plugin.

Symptom: wai snapshot fails with permission denied errors.

Fix: Ensure the data directory is readable:

ls -la ~/Photos/grandma

On macOS, you may need to grant terminal access to the Photos directory in System Settings → Privacy & Security → Files and Folders.

Symptom: wai snapshot takes a very long time or your machine runs out of memory with large data sets.

Fix: Process smaller directories at a time instead of one large snapshot:

wai snapshot ~/Photos/grandma/2020
wai snapshot ~/Photos/grandma/2021

Check your connection status and include the output when reporting an issue:

wai auth status --json