# Conversation Search Setup

> Use when the user asks to "set up conversation search", "install conversation search", "install cc-conversation-search", "/conversation-search:setup", or when the `conversation-search` run skill reports that the CLI is missing. Idempotently installs (or upgrades) the upstream `cc-conversation-search` PyPI tool via `uv tool` and initialises the local SQLite FTS5 index at `~/.conversation-search/index.db`. Safe to re-run.

- Skill: `amitkot/conversation-search-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add amitkot/conversation-search-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amitkot/conversation-search-setup/raw
- Safety review: WARNING
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: amitkot (https://skillmd.com/u/amitkot)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/amitkot/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

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

```bash
pip install --user uv
```

### 2. Install or upgrade `cc-conversation-search`

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

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

```bash
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`](https://github.com/akatz-ai/cc-conversation-search) (MIT) by `akatz-ai`. We don't vendor the Python source — upstream owns the engine, this plugin owns the workflow.