---
name: Codebase Search
slug: codebase-search
category: Automation
description: Codebase Search finds code and documentation by meaning across the indexed workspace and added knowledge bases. Use it to locate relevant files, inspect implementation, and search local sources before falling back to web search.
github: "https://github.com/Helweg/open-codebase-index/tree/main/skill"
language: TypeScript
stars: 186
forks: 29
install: "npx degit https://github.com/Helweg/open-codebase-index/tree/main/skill ~/.claude/skills/skill"
installs_to: ~/.claude/skills/skill
source_path: skill/SKILL.md
collection_size: 2
category_size: 2032
collection_url: "https://dirskills.com/collections/Helweg/open-codebase-index"
added: 2026-09-06T05:20:26.353Z
last_synced: 2026-09-06T05:20:26.353Z
canonical_url: "https://dirskills.com/skills/codebase-search"
---

# Codebase Search

Codebase Search finds code and documentation by meaning across the indexed workspace and added knowledge bases. Use it to locate relevant files, inspect implementation, and search local sources before falling back to web search.

**Install:**

```bash
npx degit https://github.com/Helweg/open-codebase-index/tree/main/skill ~/.claude/skills/skill
```

## README

# Codebase Search Skill

## Important: Indexed Content

The indexed codebase contains **two types of content**:

1. **Project Source Code** — all code files in the current workspace
2. **Knowledge Base Documentation** — external documentation, usage guides, API references, and example programs added via `add_knowledge_base` (MCP/OpenCode) or `knowledge_base_add` (Pi).

## When to Use What

| Scenario | Tool | Why |
|----------|------|-----|
| Code/library/API question | `codebase_search` | Search local knowledge first |
| Just need file locations | `codebase_peek` | Metadata only, saves ~90% tokens |
| Need to see actual code | `codebase_search` | Returns full code content |
| Find duplicates/patterns | `find_similar` | Given code snippet → similar code |
| Understand code flow | `call_graph` | Find callers/callees of any function |
| Trace dependency paths | `call_graph_path` | Find a shortest known path between two symbols |
| Analyze PR blast radius | `pr_impact` | Find affected symbols, communities, hub nodes, and risk |
| Don't know function/class names | `codebase_peek` or `codebase_search` | Natural language → code |
| Know exact identifier names | `grep` | Faster, more precise |
| Need ALL occurrences | `grep` | Semantic returns top N only |
| Access specific URL | `webfetch` | Direct URL access, no codebase search needed |
| Local search fails | `websearch` | Fallback when codebase has no results |
| Local and web search fails | suggest adding knowledge base | Notify user to add related folder |

## Search Rule

**Search local codebase first, then web search if needed.**

```
Question received
    ↓
Is this about code/library/API/framework?
    ↓ YES
codebase_search(query)
    ↓
Found relevant results? → YES → Return answer
    ↓ NO
websearch(query)
    ↓
Found relevant results? → YES → Return answer
    ↓ NO
Suggest: "知识库中未找到相关信息，是否添加相关文档文件夹？"
```

1. Use `codebase_search` for code/library/API questions
2. If no relevant results → use `websearch`
3. If web search also fails → suggest adding a knowledge base folder

## Recommended Workflow

1. **Locate by meaning first**: `codebase_peek("authentication flow")` → get likely locations before grep or graph tools
2. **Search with content**: `codebase_search("ADC channels ESP32")` → inspect implementation or knowledge-base matches
3. **Read what matters**: `Read` the specific files you need
4. **Trace structure after discovery**: `call_graph`, `call_graph_path`, `pr_impact`, or OMO CodeGraph once you know the relevant symbol
5. **Drill down with grep**: `grep "validateToken"` for exact matches

## Tools

### `codebase_peek`
Find WHERE code is. Returns metadata only (file, line, name, type).

```
codebase_peek(query="validation logic", chunkType="function", directory="src/utils")
codebase_peek(query="authentication flow", blameAuthor="jane@example.com")
```

### `codebase_search`
Find code with full content. Use when you need to see implementation.

```
codebase_search(query="error handling middleware", fileType="ts", contextLines=2)
codebase_search(query="rate limiter", blameSince="2025-01-01", blameUntil="2025-01-31")
```

### `find_similar`
Find code similar to a given snippet. Use for duplicate detection, pattern discovery, refactoring.

```
find_similar(code="function validate(input) { return input.length > 0; }", excludeFile="src/current.ts", blameSince="2025-01-01")
```

### `call_graph`
Query callers or callees of a function/method.

```
call_graph(name="validateToken", direction="callers")
```

### `index_codebase`
Manually trigger indexing. Required before first search.

### `index_status`
Check if indexed and ready.

### MCP/OpenCode knowledge-base tools

- `add_knowledge_base(path="/path/to/docs")`
- `list_knowledge_bases`
- `remove_knowledge_base(path="/path/to/docs")`

### Pi knowledge-base tools

- `knowledge_base_add(path="/path/to/docs")`
- `knowledge_base_list`
- `knowledge_base_remove(path="/path/to/docs")`

## Query Tips

**Describe behavior, not syntax:**
- Good: `"function that hashes passwords securely"`
- Bad: `"hashPassword"` (use grep for exact names)

**Search across documentation:**
- Good: `"how to configure WiFi in ESP-IDF"`
- Good: `"GPIO initialization example"`

## Filters

| Filter | Example |
|--------|---------|
| `chunkType` | `function`, `class`, `interface`, `type`, `method` |
| `directory` | `"src/api"`, `"tests"` |
| `fileType` | `"ts"`, `"py"`, `"rs"` |
| `blameAuthor` | `"jane@example.com"` or `"Jane Doe"` |
| `blameSha` | `"abc1234"` |
| `blameSince` | `"2025-01-01"` |
| `blameUntil` | `"2025-01-31"` |