conversation-search-setup

Conversation Search — setup

Install or upgrade the cc-conversation-search CLI (PyPI package owned by akatz-ai, MIT) and initialise the local index database. The actual search workflow lives in the sibling conversation-search skill — this skill only handles install/init so the hot path stays fast.

When to run this

• User explicitly asks to install / set up conversation-search.
• The conversation-search run skill bailed out with "CLI not on PATH".
• After a system upgrade where ~/.local/bin may have been wiped.

Re-running is safe. Every step is idempotent.

Steps

Run them in order. Stop at the first failure and surface a one-line diagnostic.

1. Ensure uv is available

if ! command -v uv >/dev/null 2>&1; then
  curl -LsSf https://astral.sh/uv/install.sh | sh
  # uv installs into ~/.local/bin; add it to PATH for this session
  export PATH="$HOME/.local/bin:$PATH"
fi
uv --version

If curl is unavailable (rare; locked-down corp boxes), fall back to:

pip install --user uv

2. Install or upgrade cc-conversation-search

if command -v cc-conversation-search >/dev/null 2>&1; then
  uv tool upgrade cc-conversation-search
else
  uv tool install cc-conversation-search
fi
cc-conversation-search --version

The --version line is the success check. If it doesn't print, abort.

3. Initialise the index database (only if missing)

The DB lives at ~/.conversation-search/index.db. Don't clobber an existing one:

if [ ! -f "$HOME/.conversation-search/index.db" ]; then
  cc-conversation-search init --days 7
else
  echo "Index already exists at ~/.conversation-search/index.db — skipping init."
fi

init --days 7 reads ~/.claude/projects/**/*.jsonl for the last 7 days and builds the FTS5 index. Instant, no network calls.

To re-index an existing DB (e.g., after a long gap), the user should run cc-conversation-search index --all themselves — not this setup skill.

4. Smoke-test

cc-conversation-search list --days 1 --json | head -c 200

A JSON array (possibly empty []) means the install and DB are healthy.

Report back

Print one line summarising what happened:

• cc-conversation-search vX.Y.Z installed; index initialised (N conversations).
• cc-conversation-search vX.Y.Z already installed; index already present.
• cc-conversation-search upgraded vA.B.C -> vX.Y.Z.

Then tell the user: "Setup done. You can now ask things like 'find that conversation about X' or 'what did we work on yesterday' — the conversation-search skill will handle it."

Troubleshooting

• uv tool install fails with Python interpreter not found — uv python install 3.12 first, then retry.
• init reports zero conversations — ~/.claude/projects/ is empty or unreadable. Verify ls ~/.claude/projects/ shows project directories.
• Permission errors on ~/.conversation-search/ — check the directory's owner; on shared machines it may have been created by a different user.

Upstream

This skill installs cc-conversation-search (MIT) by akatz-ai. We don't vendor the Python source — upstream owns the engine, this plugin owns the workflow.