sem — Semantic Version Control

sem extends Git with entity-level operations. Instead of "lines 43-51 changed", it tells you "function validateToken was modified in src/auth.ts". It parses 30+ languages via tree-sitter and works in any Git repo with no setup.

When to reach for sem

• User asks "what changed in this commit / PR / branch?"
• User wants to know what will break if they change a function
• User asks who last touched a function or class
• User wants to trace how a function evolved over time
• You need structured, token-efficient code context for an LLM subtask
• You're doing a code review and want entity-level signal, not line noise

Commands

sem diff — what changed?

sem diff                          # working tree changes
sem diff --staged                 # staged only
sem diff --commit abc1234         # specific commit
sem diff --from HEAD~5 --to HEAD  # commit range
sem diff file1.ts file2.ts        # compare two files (no git needed)
sem diff --format json            # structured output for further processing
sem diff --format markdown        # for PRs / reports
sem diff -v                       # verbose: word-level inline diffs
sem diff --file-exts .py .rs      # filter by extension

Change types: added, modified (structural vs cosmetic), deleted, renamed/moved.

sem impact — blast radius

sem impact validateToken          # everything affected if this changes
sem impact validateToken --deps   # direct dependencies only
sem impact validateToken --dependents  # direct dependents only
sem impact validateToken --tests  # affected tests only
sem impact validateToken --json
sem impact validateToken --file src/auth.ts  # disambiguate

Use this before refactoring or deleting a function to understand scope.

sem blame — who last touched this?

sem blame src/auth.ts             # entity-level blame for a file
sem blame src/auth.ts --json

Unlike git blame, this shows who last modified each function, not each line.

sem log — how did this evolve?

sem log validateToken             # history of a single entity
sem log validateToken -v          # with content diffs between versions
sem log validateToken --limit 20
sem log validateToken --json

sem context — token-budgeted LLM context

sem context validateToken         # entity + its deps + dependents
sem context validateToken --budget 4000
sem context validateToken --json

Use this when you need to load a function and its call graph into context without blowing the token budget.

sem entities — list all entities

sem entities                      # all entities in repo
sem entities src/auth.ts          # entities in one file
sem entities --json

sem graph — dependency visualization

sem graph                         # full cross-file dependency graph
sem graph src/                    # graph for a specific path
sem graph --format json
sem graph --file-exts .py .rs     # filter by extension

For a single entity's dependencies/dependents, use sem impact or sem context instead.

JSON output

All commands support --format json / --json. Prefer JSON when you need to process results programmatically or pass them to another tool.

{
  "summary": { "fileCount": 2, "added": 1, "modified": 1, "deleted": 1 },
  "changes": [
    {
      "entityId": "src/auth.ts::function::validateToken",
      "changeType": "modified",
      "entityType": "function",
      "entityName": "validateToken",
      "filePath": "src/auth.ts"
    }
  ]
}

MCP server

Run sem mcp to start the MCP server (stdin/stdout transport). It exposes the same operations as 6 MCP tools: sem_entities, sem_diff, sem_blame, sem_impact, sem_log, sem_context. These mirror the CLI exactly. When sem is configured as an MCP server in the agent, prefer these tools over shelling out.

Find code you don't know the name of

sem is deterministic by design — no fuzzy ranking. Locate a candidate name with a plain text search (cheap, one pass), then hand it to sem for the structure grep can't give:

grep -rn "retry" src/         # find where the concept appears
sem context retry_handler     # then: full body + callers + callees, by name

The sem_entities MCP tool also takes a query argument for the same ranked search, and sem context <entity> --hops N bounds the context to N graph hops (use 1-2 for just the immediate neighborhood). Prefer these over grep for "where is the code that does X".

Install check

sem --version   # confirm sem (not GNU Parallel's sem) is on PATH

If there's a conflict with GNU Parallel, add alias sem="$HOME/.cargo/bin/sem" to the shell profile, or use npx sem / bunx sem if installed via npm/bun.