sema

sema - Claude Code Plugin

Semantic code search and code intelligence for Claude Code.

Installation

Option 1: Add Marketplace (Recommended)

claude plugins marketplace add jrc2139/sema-plugins
claude plugins install sema

Option 2: Clone and Link

git clone https://github.com/jrc2139/sema-plugins.git
claude plugins link ./sema-plugins/packages/claude

Prerequisites

The sema binary (v0.2.0+) must be installed:

curl -fsSL https://sema.sh/install.sh | sh

Usage

Use the /sema skill or run sema directly:

Semantic Search

# 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"

Code Intelligence

Direct database queries for symbol lookup and structural filtering (requires a previously built index):

# Find symbol definitions
sema find parseConfig                # Find by exact name
sema find handle --prefix            # Prefix match
sema find init --kind function       # Filter by kind
sema find MyClass --exported         # Only exported symbols

# Find symbol references
sema refs AuthHandler                # 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

How It Works

1. Auto-Indexing: First search automatically indexes your codebase (no manual sema index required)

   • Keyword mode (-k): Builds FTS-only index instantly, no model loading
   • Hybrid mode: Shows keyword results immediately while semantic index builds in background

2. Server Lifecycle: Hybrid search spawns sema serve in the background for fast searches (~50ms)

   • Server auto-shuts down after 30 minutes of inactivity
   • SessionEnd hook cleans up any remaining processes

3. Search: Queries are sent to the server for instant results (subsequent runs)

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	Speed
Hybrid	(default)	Natural language questions	~50ms
Keyword	-k	Exact identifiers, function names	~5ms

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
}

License

AGPL-3.0