Semantic Code Search

Only use bun x codebasesearch for searching code, or execute some custom code if you need more than that, never use other cli tools to search the codebase. Search the codebase using natural language. Do multiple searches when looking for files, starting with fewer words and adding more if you need to refine the search. 102 file types are covered, returns results with file paths and line numbers.

Usage

bun x codebasesearch "your natural language query"

Invocation Examples

Via Skill Tool (Recommended - Structured JSON Input)

Basic search:

{
  "prompt": "where is authentication handled"
}

With filtering and limits:

{
  "prompt": "database connection setup",
  "filter": {
    "max-results": 20,
    "min-score": 0.7,
    "sort-by": "path"
  }
}

Scoped to directory with file type filter:

{
  "prompt": "error logging middleware",
  "context": {
    "path": "src/middleware/",
    "file-types": ["js", "ts"]
  },
  "timeout": 5000
}

Exclude patterns and narrow results:

{
  "prompt": "rate limiter implementation",
  "context": {
    "exclude-patterns": ["*.test.js", "node_modules/*"]
  },
  "filter": {
    "max-results": 10,
    "min-score": 0.8
  }
}

Legacy CLI Invocation (Still Supported)

bun x codebasesearch "where is authentication handled"
bun x codebasesearch "database connection setup"
bun x codebasesearch "how are errors logged"
bun x codebasesearch "function that parses config files"
bun x codebasesearch "where is the rate limiter"

Output Examples

Success Response (Multiple Results)

{
  "status": "success",
  "results": [
    {
      "file": "src/auth/handler.js",
      "line": 42,
      "content": "async function authenticateUser(credentials) {",
      "score": 0.95,
      "context": {
        "before": [
          "// Main authentication entry point",
          ""
        ],
        "after": [
          "  const { username, password } = credentials;",
          "  const user = await db.users.findOne({ username });"
        ]
      },
      "metadata": {
        "language": "javascript",
        "size": 2048,
        "modified": "2025-03-10T14:23:00Z"
      }
    },
    {
      "file": "src/middleware/auth-middleware.js",
      "line": 18,
      "content": "export const requireAuth = (req, res, next) => {",
      "score": 0.78,
      "metadata": {
        "language": "javascript",
        "size": 1024,
        "modified": "2025-03-10T14:20:00Z"
      }
    }
  ],
  "meta": {
    "query": "authentication handled",
    "count": 2,
    "filtered": 2,
    "duration_ms": 245,
    "scanned_files": 87,
    "timestamp": "2025-03-15T10:30:00Z"
  }
}

Empty Results Response

{
  "status": "empty",
  "results": [],
  "meta": {
    "query": "nonexistent pattern xyz123",
    "count": 0,
    "filtered": 0,
    "duration_ms": 123,
    "scanned_files": 87,
    "timestamp": "2025-03-15T10:30:00Z"
  }
}

Timeout Response (Partial Results)

{
  "status": "partial",
  "results": [
    {
      "file": "src/a.js",
      "line": 5,
      "content": "function init() {",
      "score": 0.92,
      "metadata": { "language": "javascript", "size": 512 }
    },
    {
      "file": "src/b.js",
      "line": 12,
      "content": "const setup = () => {",
      "score": 0.85,
      "metadata": { "language": "javascript", "size": 768 }
    }
  ],
  "meta": {
    "query": "expensive search pattern",
    "count": 1847,
    "filtered": 2,
    "duration_ms": 10000,
    "scanned_files": 45,
    "timestamp": "2025-03-15T10:30:00Z"
  },
  "errors": [
    {
      "code": "TIMEOUT",
      "message": "Search exceeded 10000ms limit. Returning partial results (2 of 1847 matches)."
    }
  ]
}

Error Response (Invalid Input)

{
  "status": "error",
  "results": [],
  "meta": {
    "query": null,
    "count": 0,
    "filtered": 0,
    "duration_ms": 50,
    "scanned_files": 0,
    "timestamp": "2025-03-15T10:30:00Z"
  },
  "errors": [
    {
      "code": "INVALID_PATH",
      "message": "context.path='/nonexistent' does not exist"
    },
    {
      "code": "SCHEMA_VIOLATION",
      "message": "filter.max-results must be between 1 and 500, got 1000"
    }
  ]
}

Rules

Always use this first before reading files — it returns file paths and line numbers
Natural language queries work best; be descriptive about what you're looking for
Structured JSON output includes relevance scores and file paths for immediate navigation
Use returned file paths and line numbers to read full file context via Read tool
Results are pre-sorted by relevance (highest scores first) unless sort-by specifies otherwise
Timeout queries return partial results with status=partial — use if time-critical
Schema validation ensures valid input before execution — invalid args return error with details

code-search