Sem CLI

sem-cli Skill (sem v0.24+)

This skill provides instructions on how to use sem (sem-cli), an AST entity indexer, call-graph navigator, and semantic version control tool that tracks functions, classes, methods, and types across 39 languages and data formats.

Capabilities & Limitations (What sem Does Well and Does Not Do)

What sem Does Well

• Instant Cold-Start Code Exploration: Builds an on-disk mmap query index (index.sem) that answers definition lookups (sem find), direct callers (sem callers), direct callees (sem refs), and trigram regex searches (sem grep) in ~7ms warm without running an LSP daemon.
• Signature-Only Context Packing: Fits 5–10x wider call-graph maps into LLM context windows using sem context --headers.
• Entity-Addressed Substring Search: Searches entity bodies (sem entities --text) and returns the enclosing AST entity ID (file::kind::name) rather than raw grep line numbers.
• Hotspot & Co-Change Discovery: Identifies most-modified entities and co-change pairs ("if you touch X, don't forget Y") via sem log.
• Structural Diffs & History: Shows added, modified, renamed, or deleted entities across commits without formatting or whitespace noise (structuralChange: false or --no-cosmetics).

What sem Does Not Do (Important Limitations)

• External Dependencies: sem only indexes entities defined within the local repository's source files. It does not parse or track external packages or transitive library dependencies (e.g., from pubspec.yaml, node_modules, Cargo.toml, etc.).
• External Impact Analysis: Running sem impact on an external type or class (e.g., DartType or ClassElement from an external package) will fail with error: Entity '...' not found.
• Workflow for External Packages: If tasked with evaluating how an external package is used across a codebase, do not start with sem. Use standard grep or ripgrep (sem grep or rg) to find import statements and locate local wrapper classes or helper functions. Once local wrapper entities are identified, use sem impact on those local entities to trace their usage across the codebase.

Finding Entities (<entity_name>)

Many sem commands require an <entity_name>. Discover exact names or IDs using:

1. Instant Cold-Start Lookups (sem find / sem callers / sem refs): Backed by an on-disk mmap-able query index (index.sem), warm lookups take ~7ms without a daemon:

   # Find where an entity is defined
   sem find "function diff_command" --json
   
   # Who calls it directly
   sem callers diff_command --json
   
   # What it calls directly
   sem refs diff_command --json
   

2. Entity-Addressed Substring Search (sem entities --text): Search entity bodies for an exact substring and get back the enclosing AST entity ID (file::kind::name), avoiding manual line-to-function mapping:

   # Search for a string inside entity bodies and return enclosing entity IDs
   sem entities src/ --text "PERMISSION_DENIED" --json
   
   # Filter by AST entity kind (--only / --except)
   sem entities src/ --only function --only class --json
   

3. Entity IDs for Disambiguation: If a name is ambiguous (e.g., multiple files define a setup() function), pass --file <path> or use the fully qualified entity_id returned by --json output (e.g., --entity-id "src/utils.ts::function::setup").

Core Commands & Flag Reference (sem v0.24+)

Important Flag Distinction (--format vs. --json):

• Only sem diff uses --format <json|markdown|plain>.
• All other subcommands (sem impact, sem blame, sem log, sem entities, sem context, sem find, sem callers, sem refs, sem grep, sem graph) use --json directly. Do not pass --format json to sem impact or sem log.

1. Semantic Diff (sem diff)

Show added, modified, deleted, renamed, or moved entities in the working tree, between commits, between any two files, or piped from unified diffs.

# View semantic changes in working directory
sem diff

# View only staged changes
sem diff --staged

# Strip formatting, whitespace, and comment-only changes
sem diff --no-cosmetics

# Show changes from a specific commit or range
sem diff --commit <COMMIT>
sem diff --from <COMMIT_1> --to <COMMIT_2>

# Verbose inline word-level diffs for modified entities
sem diff -v

# Output formats: json, markdown, or plain
sem diff --format json
sem diff --format markdown

# Pipe any unified diff via stdin (works in Jujutsu / CitC workspaces without .git)
jj diff --git | sem diff --patch --no-cosmetics --format json

# Compare any two files directly (no git repo required)
sem diff file1.dart file2.dart

Additional options: --file-exts <EXTS>... (Filter by extensions, e.g., --file-exts .dart).

2. Impact Analysis (sem impact)

Analyze the transitive impact of changing an entity (BFS traversal).

# Full transitive impact analysis in JSON
sem impact <entity_name> --json

# Disambiguate by file or fully qualified ID
sem impact setup --file src/test_utils.ts --json
sem impact --entity-id "src/utils.ts::function::setup" --json

# Direct dependencies or dependents only
sem impact <entity_name> --deps --json
sem impact <entity_name> --dependents --json

# Show only affected tests (uses call graph + lexical/IDF fallback)
sem impact <entity_name> --tests --json

# Include generated, fixture, vendor, benchmark, and build trees
sem impact <entity_name> --no-default-excludes --json

3. Repository Hotspots & Entity History (sem log)

Show the evolution of an entity through git history, or analyze repository-wide churn and co-change pairs.

# Repository hotspots (most-modified entities + author counts) & co-change pairs
sem log --limit 200 --json

# Scoped hotspots & co-change pairs for a specific directory/file
sem log --file src/auth.ts --json

# Track a specific entity's evolution through git history
sem log <entity_name> --json
sem log <entity_name> -v

4. Instant Index Lookups (sem find, sem callers, sem refs, sem grep)

Fast cold/warm lookups backed by index.sem:

# Locate entity definition
sem find <entity_name> --json

# Direct callers of an entity
sem callers <entity_name> --json

# Direct callees referenced by an entity
sem refs <entity_name> --json

# Trigram text search across indexed source files
sem grep "TODO"

5. Token-Budgeted Context (sem context)

Fit an entity, its dependencies, and its dependents into a strict token budget for LLM consumption:

# Standard full-body context packing
sem context <entity_name> --budget 8000 --json

# Signature-only packing (signature + first doc-comment line; ~5-10x wider map)
sem context <entity_name> --headers --budget 4000 --json

# Pack multiple entities into a single shared budget, bounded by graph hops
sem context --entity <entity_A> --entity <entity_B> --hops 2 --headers --budget 6000 --json

6. Dependency Graph (sem graph) & Entity Blame (sem blame)

# Full entity dependency graph edge list
sem graph --json

# Entity-level git blame for a file
sem blame <file_path> --json

Troubleshooting & Environment Gotchas

• GNU Parallel Binary Collision (/usr/bin/sem): GNU Parallel installs /usr/bin/sem as a symlink to parallel. If sem hangs or rejects subcommands, verify the binary with sem --version or which sem. Ensure Homebrew ($(brew --prefix)/bin/sem) or Cargo (~/.cargo/bin/sem) precedes /usr/bin in PATH.
• Asynchronous Execution for Large Graphs: On very large repositories, the initial index/graph build can take several seconds. Run sem impact or sem graph with a background timeout (WaitMsBeforeAsync) if cold-starting on a massive monorepo.