sem

---
name: sem
description: Use sem to get entity-level (function/class/method) semantic diffs, impact analysis, blame, and dependency context from any Git repo. Trigger this skill whenever the user asks what changed in a commit or PR, wants to understand the blast radius of a change, needs to know who last modified a function, wants to trace how a function evolved, or needs structured code context for an LLM task. Also use it proactively when reviewing code, planning refactors, or any time line-level git diff output would be noisy or hard to interpret.
license: MIT OR Apache-2.0
compatibility: Requires the sem CLI (https://github.com/Ataraxy-Labs/sem) on PATH and a Git repository
metadata:
  homepage: https://github.com/Ataraxy-Labs/sem
---

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

```bash
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

```bash
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?

```bash
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?

```bash
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

```bash
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

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

### sem graph — dependency visualization

```bash
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.

```json
{
  "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:

```bash
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

```bash
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.