Sem

Part of the [Ataraxy Labs](https://ataraxy-labs.com) stack: agent-native infrastructure for software development. See also: weave (entity-level git merge driver) · inspect (semantic code review) · opensessions (tmux sidebar for coding agents).

Read the manifesto: https://ataraxy-labs.com/#thesis · Essays: https://ataraxy-labs.com/blogs · LLMs: https://ataraxy-labs.com/llms.txt

Semantic version control built on Git.

Instead of lines changed, sem tells you what entities changed: functions, methods, classes.

Why sem? · Using sem with agents · Install · Commands · Agents (MCP) · Cloud consent · Releases

sem is a semantic version control tool that works on top of Git. It parses your code with tree-sitter, extracts every function, class, and method as an entity, and diffs at the entity level instead of lines. This means you see "function blahh was modified" instead of "lines x-y changed."

It works in any Git repo with no setup.

Cloud-backed queries are opt-in per repo: logging in does not upload a repo or send a query. See the cloud consent flow for the public/private repo states, preview screen, local audit log, and forget controls.

Using sem with agents

Four questions, four verbs. Every verb takes --json.

Where is it? Find a function, class or method by name:

sem find parse_config

function parse_config src/config.py:1

Who calls it (--callers), what it uses (--refs), or its code with its callers and callees (--context):

sem find parse_config --callers

function parse_config src/config.py:1

function load src/config.py:6 function test_parse_config tests/test_config.py:4

Search text, like rg:

sem grep splitlines

src/config.py:2:    pairs = [line.split("=", 1) for line in text.splitlines() if line]

What does my change touch? Everything that depends on an entity, and the tests to run:

sem impact parse_config --tests

⚡ 1 tests affected:

tests/test_config.py function test_parse_config (L4–5)

sem impact --diff HEAD --tests answers the same for your whole uncommitted change.

Is it correct? Run the project's own compiler, type checker, linter and tests, rechecking only what the change can affect when that gives the same answer. Exit 0 means pass, 1 fail, 2 could not decide:

sem check

cmd    FAIL      full        sh (0 rechecked, 279 ms)

python3 -m pytest -q tests exited 1: E AssertionError: assert {'a': '1'} == {'a': '2'}

What should a human review? A review certificate for a commit range: what changed, which callers the change leaves behind, which tests reach it:

sem certify main..HEAD

# sem certificate 94f4bd74e26e..d73d4d092b43

1 files, 2 entities changed (1 added, 1 modified, 0 deleted, 0 renamed, 0 moved).

• modified parse_config (src/config.py:1): 2 static caller(s) in 2 file(s) that this change does not modify

For agents that speak MCP, sem mcp serves the same verbs as tools (see Use with AI agents).

Install

curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh

Or via Homebrew:

brew install sem-cli

Or via winget on Windows:

winget install AtaraxyLabs.sem

Or via Scoop on Windows:

scoop install sem

Or install the npm wrapper into node_modules:

npm install --save-dev @ataraxy-labs/sem

With Bun, trust the package so its postinstall script can download the binary:

bun add -d @ataraxy-labs/sem

bun pm trust @ataraxy-labs/sem

Once installed, update to the latest release any time:

sem config update

Or via cargo, from crates.io:

cargo install sem-cli

Or build the latest main from source (requires Rust):

cargo install --git https://github.com/Ataraxy-Labs/sem sem-cli

Or grab a binary from GitHub Releases.

Or run via Docker:

docker build -t sem .

docker run --rm -it -u "$(id -u):$(id -g)" -v "$(pwd):/repo" sem diff

Name conflict with GNU Parallel

GNU Parallel ships a sem binary (/usr/bin/sem) as a symlink to parallel. If you have both installed, they'll collide. Run sem --version to check which one you're using. (#77)

Quick fixes:

# Option 1: alias in your shell profile (~/.bashrc, ~/.zshrc)

alias sem="$HOME/.cargo/bin/sem"

Option 2: make sure cargo bin comes first in PATH

export PATH="$HOME/.cargo/bin:$PATH"

Option 3: if installed via Homebrew

export PATH="$(brew --prefix)/bin:$PATH"

If you installed via npm/bun, the binary lives in node_modules/.bin/sem and is invoked through npx sem or bunx sem, which avoids the conflict entirely.

Commands

Works in any Git repo. No setup required. Also works outside Git for arbitrary file comparison.

sem --help shows every flag with an example.

sem stores its SQLite entity cache outside the repository, under the OS cache directory by default. Set SEM_CACHE_DIR=/path/to/cache to override the cache root; repo-local overrides are ignored so cache files do not dirty the working tree.

sem find

Find entity definitions by name, then ask about one: who calls it, what it uses, or its code with the code around it. Answers come from an on-disk query index (index.sem, next to the entity cache); the first call in a repo builds it, later calls read it directly, with no daemon.

sem find "function diff_command"        # where it is defined ("type name" narrows by kind)

sem find diff_command load_config # several names in one call sem find diff_command --callers # who calls it; says when the caller set may be incomplete sem find diff_command --refs # what it calls and references sem find diff_command --context # its code plus callers and callees, within a token budget sem find diff_command --context --budget 4000 --hops 1 sem find --in src/auth.ts # every entity in a file or directory sem find diff_command --in src/ # only definitions under src/ sem find --text "retry budget" # entity bodies containing a string, named by entity sem find diff_command --json # JSON on any of the above

With --context, when the target signature itself does not fit, JSON output reports target_omitted: true.

sem grep

Text search across source files, rg-compatible file:line:text output, served from the index's trigram postings when one exists.

sem grep "TODO"

sem grep -i todo src/ # case-insensitive, under src/ sem grep -e foo -e bar --json # several patterns, hits kept apart

sem impact

What breaks if an entity changes: its dependencies, its dependents (transitively), and the tests that reach it.

sem impact authenticateUser             # full impact

sem impact authenticateUser --deps # direct dependencies only sem impact authenticateUser --dependents sem impact authenticateUser --tests # the tests to run sem impact authenticateUser --file src/auth.ts # disambiguate by file sem impact --diff HEAD --tests # tests for the uncommitted change sem impact --diff main..HEAD --json # one impact report per changed entity

With --diff and --tests in a JS/TS workspace, the answer is the module graph's affected-test selection over the changed files (sem graph --modules affected-tests); elsewhere it is the entity graph's. --no-default-excludes includes generated, fixture, vendor, benchmark and build trees.

sem check

Runs the project's compiler, type checker, linter and tests on the working tree and prints one verdict: exit 0 pass, 1 fail, 2 could not decide. Each checker gives the verdict the real tool would give on the whole project; it rechecks only what the change can affect when that is provably the same answer, and otherwise runs the tool in full and says why. Nothing to check is 2, never a pass.

sem check                               # every checker the project has

sem check --checkers ts,lint,tests # only these sem check --base origin/main # against origin/main instead of HEAD sem check --promises # also prove every promise in .sem/promises can fail sem check --json # one JSON object with a verification certificate

Checkers are detected from the project. TypeScript, lint and JS tests (vitest, jest) follow the module graph, Go rechecks affected packages, Python type checking (pyright scoped by imports, or mypy) and pytest rerun only the files a change can reach, and C and C++ recompile only the translation units in compile_commands.json that include a changed file. Cargo, Gradle or Maven, dotnet and SwiftPM run their own build, which already rebuilds only what changed, and are skipped outright when no input changed since the base passed (a TypeScript edit never reruns the Rust build).

An edit inside the body of a Python function that declares its return type cannot change what other files see, so only that file is rechecked.

Commands of your own go in .sem/check.json, e.g. {"commands": [{"run": "make lint", "inputs": ["src/**"]}]}. A command that lists its inputs is skipped when none of them changed since it passed; one without runs every time.

sem certify

A review certificate for a commit range: entities touche