Sourcebot Guide

When to Use

• External library research: Finding code patterns in Effect-TS, TanStack, Vercel AI SDK, etc.
• API discovery: Understanding how external libraries implement specific features
• Documentation examples: Finding real-world usage examples from official repositories
• Framework patterns: Learning best practices from external framework codebases
• Migration guidance: Finding upgrade patterns and breaking changes in external libraries

When NOT to Use

• Local project code: Use

  codebase_search

  or

  osgrep search

  instead
• Local components: Use local search tools for project files
• Local utilities: Never use Sourcebot for your own codebase

Required Workflow

1. First, call

   list_repos

   to get available repository IDs
2. Identify relevant repository ID(s) for your search (e.g., "Effect-TS/effect" for EffectTS)
3. Always include

   filterByRepoIds

   when calling

   search_code

4. Use

   get_file_source

   to fetch specific file contents when needed

Repository ID Format

• CRITICAL: Repository IDs must be in format

  "owner/repo"

  (e.g.,

  "Effect-TS/effect"

  ,

  "vercel/ai"

  )
• DO NOT include the

  github.com/

  prefix
• The

  list_repos

  tool returns IDs like

  "github.com/owner/repo"

  - strip the prefix when using in

  filterByRepoIds

Usage Examples

Searching EffectTS patterns

{
  "query": "Effect.gen yield",
  "filterByRepoIds": ["Effect-TS/effect"],
  "includeCodeSnippets": true
}

Searching AI SDK

{
  "query": "streamText tool calling",
  "filterByRepoIds": ["vercel/ai"],
  "includeCodeSnippets": true
}

Searching multiple repos

{
  "query": "error handling patterns",
  "filterByRepoIds": ["Effect-TS/effect", "vercel/ai"],
  "includeCodeSnippets": true
}

Best Practices

• Use descriptive queries (not just keywords, but full descriptions)
• Always specify

  filterByRepoIds

  to scope searches
• Set

  includeCodeSnippets: true

  when you need actual code examples
• Use

  get_file_source

  after finding relevant files to see full context

Tool Hierarchy for Code Search

1. Sourcebot - For EXTERNAL libraries and frameworks only

2. codebase_search

   (if available) - For local project code

3. osgrep search

   - For local code when codebase_search unavailable

4. grep

   /

   find

   - Last resort for exact string matching

Critical Requirements

• MANDATORY: Use Sourcebot MCP 5-7 times when researching external libraries
• CRITICAL: NEVER use Sourcebot to search local project code
• CRITICAL: Always use

  filterByRepoIds

  on EVERY

  search_code

  call
• TASK INVALIDATION: Task will be invalidated if you don't use Sourcebot 5-7 times when dealing with external libraries
• AFTER SOURCEBOT: Also use Perplexity and Context7 for updated information on external libraries