GitHub Code Search via grep.app

Overview

This skill enables searching across millions of public GitHub repositories using the grep.app service. It uses a code mode pattern where you write and execute TypeScript code to query the grep.app MCP server, filter results locally, and return only relevant findings.

When to Use

• Find implementations of specific patterns (e.g., "how do other projects implement OAuth2?")
• Search for usage examples of APIs or libraries
• Analyze architectural patterns across codebases
• Find code snippets matching regex patterns
• Research best practices by examining popular repositories

Setup Requirements

The grep.app MCP server must be configured. Add it with:

claude mcp add --transport http grep https://mcp.grep.app

Verify with /mcp - you should see grep listed.

Code Mode Pattern

Instead of calling MCP tools directly (which loads all tool definitions into context), this skill uses code execution for efficiency:

1. Write TypeScript code that calls the grep MCP server
2. Execute the code via Bash with bun or npx tsx
3. Filter and process results in the execution environment
4. Return only relevant findings to minimize token usage

This approach reduces token usage by 90%+ compared to direct tool calls with large result sets.

Implementation

Option 1: Use the bundled search script (recommended)

A ready-to-use TypeScript search script is included:

bun run skills/github-code-search/scripts/search.ts "query" [--lang=Language] [--repo=owner/repo] [--limit=N] [--regexp]

Examples:

# Search for "use cache" in TypeScript files
bun run skills/github-code-search/scripts/search.ts "use cache" --lang=TypeScript --limit=5

# Search in a specific repository
bun run skills/github-code-search/scripts/search.ts "cacheLife" --repo=vercel/next.js --limit=10

# Use regex patterns
bun run skills/github-code-search/scripts/search.ts "async.*await" --regexp --lang=TypeScript

Output format (JSON):

{
  "query": "cacheLife",
  "options": { "language": "TypeScript", "limit": 3 },
  "total": 2931,
  "results": [
    {
      "repo": "vercel/next.js",
      "path": "packages/next/src/server/use-cache/cache-life.ts",
      "url": "https://github.com/vercel/next.js/blob/canary/packages/next/src/server/use-cache/cache-life.ts",
      "matches": [{ "lineNumber": 5, "content": "export type »CacheLife« = {" }]
    }
  ]
}

The » and « markers indicate where the search term was matched.

Option 2: Inline TypeScript (for custom processing)

For more complex searches with custom filtering, write inline TypeScript:

// Execute with: bun -e "..."
const response = await fetch(
  'https://grep.app/api/search?q=useOptimistic&l=TypeScript'
)
const data = await response.json()

// Process results locally - this is the efficiency gain!
const filtered = data.hits.hits
  .filter((hit: any) => hit.repo.includes('react'))
  .slice(0, 5)
  .map((hit: any) => ({ repo: hit.repo, path: hit.path }))

console.log(JSON.stringify(filtered, null, 2))

Quick Search (Direct API)

For simple searches, use curl directly:

curl -s "https://grep.app/api/search?q=useOptimistic+hook&l=TypeScript" | jq '.hits.hits[:5] | .[] | {repo: .repo.raw, path: .path.raw}'

Parameters

Example Queries

Find "use cache" implementations in Next.js projects

curl -s "https://grep.app/api/search?q=%22use%20cache%22&l=TypeScript" | jq '.hits.hits[:10] | .[] | {repo: .repo.raw, path: .path.raw}'

Search for error handling patterns

curl -s "https://grep.app/api/search?q=catch.*error.*log&regexp=true&l=TypeScript" | jq '.hits.total'

Find implementations in a specific repo

curl -s "https://grep.app/api/search?q=cacheLife&r=vercel/next.js" | jq '.hits.hits[] | {path: .path.raw, lines: .content.lines}'

Best Practices

1. Start broad, then narrow: Begin with a general query, then add language/repo filters
2. Use regex for patterns: Enable regexp=true for complex pattern matching
3. Limit results locally: Process and filter in code before returning to save tokens
4. Cache common searches: Store results for frequently-used queries
5. Respect rate limits: The grep.app API has rate limits; batch queries when possible

Integration with MCP Tools

If the grep MCP server is configured, you can also use it via MCP tools:

// Via MCP (if mcp__grep__search is available)
mcp__grep__search({
  query: 'authentication middleware',
  language: 'TypeScript',
  useRegexp: false,
})

However, the code mode approach (curl + jq or TypeScript script) is preferred for:

• Large result sets that need filtering
• Complex post-processing logic
• Chaining multiple searches
• Minimizing context window usage

Troubleshooting

• No results: Try broadening the query or removing filters
• Rate limited: Wait a few seconds and retry, or use the MCP server which may have higher limits
• Timeout: Large queries may timeout; add more specific filters