sema

sema - Semantic Code Search & Code Intelligence

Requires sema v0.2.0+. First search automatically indexes your codebase (no manual setup needed). Use sema "<query>" for semantic code search. Hybrid search (semantic + keyword) is the default.

Code Intelligence Commands

Direct database queries for symbol lookup and structural filtering. These require a previously built index (automatic on first search).

# Find symbol definitions
sema find <symbol>                   # Find by exact name
sema find <symbol> --prefix          # Prefix match
sema find <symbol> --kind function   # Filter by kind (function, class, method, etc.)
sema find <symbol> --exported        # Only exported symbols
sema find <symbol> --semantic        # Semantic search for similar symbols (requires server)
sema find <symbol> --refs            # Include references alongside definitions

# Find symbol references
sema refs <symbol>                   # Find chunks that reference a symbol

# Query by structural metadata
sema query --kind function --exported --no-docstring      # Undocumented public functions
sema query --kind method --min-complexity 10              # Complex methods
sema query --role test --language zig                     # All test code in Zig
sema query --parent MyClass --kind method                 # All methods in MyClass

File Outline, Impact Analysis & Codebase Map

# Show file skeleton with symbol nesting
sema outline <file>                  # Compact view
sema outline <file> -v               # Include signatures

# Impact analysis: where is a symbol used?
sema blast <symbol>                  # Definition + grouped references

# Codebase map: cluster files by semantic similarity
sema map                             # Auto-detect cluster count
sema map --clusters 5                # Force 5 clusters
sema map --depth 2                   # Hierarchical sub-clustering
sema map --json                      # JSON output

Query Filters

• --kind <type>: function, class, method, struct, enum, interface, etc.
• --exported: Only exported/public symbols
• --no-docstring: Symbols without documentation
• --has-docstring: Symbols with documentation
• --min-complexity N: Minimum cyclomatic complexity
• --max-complexity N: Maximum cyclomatic complexity
• --role <role>: definition, test, configuration
• --parent <symbol>: Filter by parent symbol
• -l, --language <lang>: Filter by language
• -n <n>: Max results (default: 5)

Usage

# Hybrid search (default) - best for natural language questions
sema "where is authentication handled?"
sema "error handling patterns" -l python

# Keyword search (-k) - fast, no model loading, good for identifiers
sema -k "parseArgs"
sema -k "ConfigLoader"

# Search within a directory
sema "API endpoints" src/
sema "database queries" ./backend/

# With filters
sema "error handling" -l zig -n 10
sema -g "src/**/*.ts" "authentication"
sema --exclude "**/tests/*" "main function"

Options

• <path>: Search within directory (positional, e.g., sema "query" src/)
• -k, --keyword: BM25 text search (no model loading, instant)
• -n <num>: Max results (default: 5)
• -l <lang>: Filter by language (python, javascript, zig, etc.)
• -g <pattern>: Filter by file path glob (e.g., "src/**/*.ts")
• --exclude <pattern>: Exclude files matching glob pattern (e.g., "**/tests/", ".md")
• -c, --compact: File paths only

Search Modes

Mode	Flag	Best For	First Run	Speed
Hybrid	(default)	Natural language questions	Keyword results immediately; run sema index for semantic	~50ms (subsequent)
Keyword	-k	Exact identifiers, function names	FTS-only index built instantly, no model loading	~5ms

Auto-Indexing: On first search, sema builds a keyword (FTS) index automatically.

• Keyword mode (-k): FTS-only, instant, no model needed
• Hybrid mode (default): Shows keyword results. Run sema index for full semantic search
• Set auto_embed: true in config to auto-download model and embed on first search

Server Lifecycle: The server auto-starts when embeddings exist and auto-shuts down after 30 minutes of inactivity.

Semantic Indexing (Agent Guidance)

If the user wants semantic (hybrid) search and no index exists yet, offer to run sema index in the background:

sema index .   # Downloads model on first run, then indexes

• Ask permission first -- indexing is CPU-intensive and can take minutes on large codebases
• Run in background -- use run_in_background: true so the user can keep working
• Notify on completion -- tell the user when indexing finishes
• Set expectations -- "This may take a few minutes on a large codebase and will use significant CPU while running"
• Stop the server -- if the user wants to free resources: sema stop
• Check status -- sema list shows running servers and sema doctor checks system health

When to Use

Use sema find:

• "Show me the definition of parseConfig"
• "Where is AuthHandler defined?"
• "Find all exported functions starting with 'handle'"

Use sema refs:

• "Where is this function called?"
• "Find all references to this symbol"

Use sema query:

• "Show me all undocumented public functions"
• "Find complex methods (high cyclomatic complexity)"
• "List all test functions in this codebase"
• "Show me configuration-related symbols"

Use sema outline:

• "What symbols are in this file?"
• "Show me the structure of engine.zig"

Use sema blast:

• "What would break if I change this function?"
• "How widely is this symbol used?"

Use sema map:

• "Give me an overview of this codebase"
• "How is the code organized?"
• "What are the main components/modules?"

Use sema (hybrid search):

• "Where is authentication handled?"
• "How does Y work?"
• Finding code by concept/meaning

Use sema -k (keyword search):

• Searching for specific function/class names
• Finding exact identifiers
• When you know the exact term

Use grep:

• Exact string literals
• Regex patterns

Configuration

Configure sema behavior in .sema/config.json or ~/.config/sema/config.json:

Search Mode (db.mode):

• "hybrid" (default): Semantic + keyword search. Loads embedding model, best for natural language queries
• "keyword": FTS-only search. No model loading, instant ~5ms startup, good for identifiers

Embedding Models (default: e5-small-v2):

• e5-small-v2: Small, 256 dimensions, balanced speed/quality (default)
• e5-large-v2: Larger model, better semantic understanding
• embeddinggemma-300m: Gemma-based embedder, good for domain-specific code

Example config:

{
    "db": {
        "mode": "hybrid"
    }
}

Ignore Patterns

By default, sema respects .gitignore files when indexing. You can also use .semaignore files for sema-specific exclusions (same syntax as .gitignore):

# .semaignore - exclude from sema but keep in git
generated/
*.min.js
vendor/

.semaignore files work at any directory level, just like .gitignore.

To index everything (ignore no patterns):

sema index --no-gitignore .

Or in config:

{
    "respect_ignore": false
}