tim-hub/kb-search

Search the knowledge base and local files using ripgrep, returning the most relevant results.

Setup Check

Before searching, verify the KB is configured:

cat ~/.kb/config.json 2>/dev/null

If the config is missing or empty, invoke the kb-setup skill first.

Read Config

Load search paths from ~/.kb/config.json:

• allow_list — paths to search (can include any directories, not just the kb/ subfolder)
• disallow_list — paths to exclude from search results

Keyword Expansion

The user's input keyword is a starting point — expand it to find more relevant results:

1. Extract the core search term from the argument.
2. Generate 2-4 related/synonymous keywords (e.g., "JWT" → also try "token", "auth", "bearer").
3. Pass each keyword to scripts/search.sh in parallel (up to the limit).

This expansion catches results the user would expect even when they phrase things differently from how they were written.

Run Search

For each keyword variant, run in parallel:

bash <skill-dir>/scripts/search.sh "<keyword>" "<allow_list_json>" "<disallow_list_json>"

Collect all results. The script returns matching lines with file paths and context.

Result Ranking and Filtering

From all parallel results:

1. Deduplicate results that appear for multiple keyword variants (same file + line number).
2. Rank by relevance — prefer results where:
   • The keyword appears in a heading (##) over body text
   • Multiple keyword variants matched the same file/section
3. Show the top 3 results by rank. Do not suppress or hide results because they seem tangential — the user decides what's useful, not you. If ripgrep found a match, surface it.

Output Format

Present results clearly. For each result:

• Convert the absolute file path to a ~/... path (replace the home directory prefix with ~)
• Format the path as a markdown link so the user can navigate to the file: [~/relative/path](file:///absolute/path)

## Search Results for "<query>"

### 1. [Topic from heading or filename]
[~/relative/path/to/file.md](file:///absolute/path/to/file.md)
> <matching excerpt, 2-4 lines of context>

### 2. [Topic from heading or filename]
[~/relative/path/to/file.md](file:///absolute/path/to/file.md)
> <matching excerpt, 2-4 lines of context>

### 3. [Topic from heading or filename]
[~/relative/path/to/file.md](file:///absolute/path/to/file.md)
> <matching excerpt, 2-4 lines of context>

Only say "no results found" if ripgrep returned zero matches. If there were matches, show them.

References

• Script: scripts/search.sh — ripgrep wrapper with allow/disallow list support