{ "markdown": "> **Part of the [Ataraxy Labs](https://ataraxy-labs.com) stack**: agent-native infrastructure for software development. See also: [weave](https://ataraxy-labs.com/weave) (entity-level git merge driver) · [inspect](https://github.com/Ataraxy-Labs/inspect) (semantic code review) · [opensessions](https://github.com/Ataraxy-Labs/opensessions) (tmux sidebar for coding agents).\n>\n> Read the manifesto: https://ataraxy-labs.com/#thesis · Essays: https://ataraxy-labs.com/blogs · LLMs: https://ataraxy-labs.com/llms.txt\n\n

\n \"sem\"\n

\n\n

\n \"Ataraxy-Labs%2Fsem\n

\n\n

\n Semantic version control built on Git.
\n Instead of lines changed, sem tells you what entities changed: functions, methods, classes.\n

\n\n

\n Why sem? ·\n Install ·\n Commands ·\n Agents (MCP) ·\n Cloud consent ·\n Releases\n

\n\n

\n \"Release\"\n \"Rust\"\n \"Tests\"\n \"License\"\n \"Languages\"\n

\n\nsem 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.\"\n\nIt works in any Git repo with no setup.\n\nCloud-backed queries are opt-in per repo: logging in does not upload a repo or send a query. See the [cloud consent flow](docs/cloud-consent.html) for the public/private repo states, preview screen, local audit log, and forget controls.\n\n

\n \"sem\n

\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh\n```\n\nOr via Homebrew:\n\n```bash\nbrew install sem-cli\n```\n\nOr via winget on Windows:\n\n```powershell\nwinget install AtaraxyLabs.sem\n```\n\nOr via Scoop on Windows:\n\n```powershell\nscoop install sem\n```\n\nOr install the npm wrapper into `node_modules`:\n\n```bash\nnpm install --save-dev @ataraxy-labs/sem\n```\n\nWith Bun, trust the package so its `postinstall` script can download the binary:\n\n```bash\nbun add -d @ataraxy-labs/sem\nbun pm trust @ataraxy-labs/sem\n```\n\nOnce installed, update to the latest release any time:\n\n```bash\nsem update\n```\n\nOr via cargo, from [crates.io](https://crates.io/crates/sem-cli):\n\n```bash\ncargo install sem-cli\n```\n\nOr build the latest `main` from source (requires Rust):\n\n```bash\ncargo install --git https://github.com/Ataraxy-Labs/sem sem-cli\n```\n\nOr grab a binary from [GitHub Releases](https://github.com/Ataraxy-Labs/sem/releases).\n\nOr run via Docker:\n\n```bash\ndocker build -t sem .\ndocker run --rm -it -u \"$(id -u):$(id -g)\" -v \"$(pwd):/repo\" sem diff\n```\n\n## Name conflict with GNU Parallel\n\nGNU 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](https://github.com/Ataraxy-Labs/sem/issues/77))\n\n**Quick fixes:**\n\n```bash\n# Option 1: alias in your shell profile (~/.bashrc, ~/.zshrc)\nalias sem=\"$HOME/.cargo/bin/sem\"\n\n# Option 2: make sure cargo bin comes first in PATH\nexport PATH=\"$HOME/.cargo/bin:$PATH\"\n\n# Option 3: if installed via Homebrew\nexport PATH=\"$(brew --prefix)/bin:$PATH\"\n```\n\nIf 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.\n\n## Commands\n\nWorks in any Git repo. No setup required. Also works outside Git for arbitrary file comparison.\n\nsem 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.\n\n### sem diff\n\nEntity-level diff with rename detection, structural hashing, and word-level inline highlights.\n\n```bash\n# Semantic diff of working changes\nsem diff\n\n# Staged changes only\nsem diff --staged\n\n# Specific commit\nsem diff --commit abc1234\n\n# Commit range\nsem diff --from HEAD~5 --to HEAD\n\n# Verbose mode (word-level inline diffs for each entity)\nsem diff -v\n\n# Plain text output (git status style)\nsem diff --format plain\n\n# JSON output (for AI agents, CI pipelines)\nsem diff --format json\n\n# Markdown output (for PRs, reports)\nsem diff --format markdown\n\n# Compare any two files (no git repo needed)\nsem diff file1.ts file2.ts\n\n# Read file changes from stdin (no git repo needed)\necho '[{\"filePath\":\"src/main.rs\",\"status\":\"modified\",\"beforeContent\":\"...\",\"afterContent\":\"...\"}]' \\\n | sem diff --stdin --format json\n\n# Only specific file types\nsem diff --file-exts .py .rs\n```\n\n### sem impact\n\nCross-file dependency graph shows what breaks if an entity changes.\n\n```bash\n# Full impact analysis\nsem impact authenticateUser\n\n# Direct dependencies only\nsem impact authenticateUser --deps\n\n# Direct dependents only\nsem impact authenticateUser --dependents\n\n# Affected tests only\nsem impact authenticateUser --tests\n\n# JSON output\nsem impact authenticateUser --json\n\n# Disambiguate by file\nsem impact authenticateUser --file src/auth.ts\n\n# Include default-excluded paths such as generated, fixture, vendor, benchmark, and build trees\nsem impact authenticateUser --no-default-excludes\n```\n\n### sem blame\n\nEntity-level blame showing who last modified each function, class, or method.\n\n```bash\nsem blame src/auth.ts\n\n# JSON output\nsem blame src/auth.ts --json\n```\n\n### sem log\n\nTrack how a single entity evolved through git history.\n\n```bash\nsem log authenticateUser\n\n# Verbose mode (show content diff between versions)\nsem log authenticateUser -v\n\n# Limit commits scanned\nsem log authenticateUser --limit 20\n\n# JSON output\nsem log authenticateUser --json\n```\n\nWith no entity, `sem log` analyzes recent repo history at the entity level:\n**hotspots** (most-changed functions/classes, with author counts) and\n**co-change pairs** (entities that repeatedly change in the same commits:\n\"if you touch one, don't forget the other\"):\n\n```bash\nsem log # repo hotspots + co-change pairs (last 50 commits)\nsem log --limit 200 # deeper history\nsem log --file src/auth.ts # scoped to one file\nsem log --json # full data\n```\n\n### sem entities\n\nList all entities under a file or directory path. No path is the same as `.`.\n\n```bash\nsem entities\n\nsem entities .\n\nsem entities src/auth.ts\n\n# JSON output\nsem entities --json\nsem entities src/auth.ts --json\n\n# Include default-excluded paths such as generated, fixture, vendor, benchmark, and build trees\nsem entities --no-default-excludes\n```\n\n### sem context\n\nToken-budgeted context for LLMs: the entity, its dependencies, and its dependents, fitted to a strict content token budget.\nWhen the target signature itself does not fit, JSON output reports `target_omitted: true`.\n\n```bash\nsem context authenticateUser\n\n# Custom token budget\nsem context authenticateUser --budget 4000\n\n# JSON output\nsem context authenticateUser --json\n\n# Include default-excluded paths such as generated, fixture, vendor, benchmark, and build trees\nsem context authenticateUser --no-default-excludes\n```\n\n### sem find / callers / refs / grep\n\nCold-start lookups backed by an on-disk, mmap-able query index (`index.sem`, stored next to the SQLite entity cache). The first call in a repo builds the index; every call after that reads it directly, no daemon or background process involved:\n\n```bash\n# Find where an entity is defined\nsem find \"function diff_command\"\n\n# Who calls it\nsem callers diff_command\n\n# What it calls\nsem refs diff_command\n\n# Text search across source files (rg-compatible file:line:text output,\n# served from the index's trigram postings when one exists)\nsem grep \"TODO\"\n\n# JSON output on any of the above\nsem find diff_command --json\n```\n\nMeasured on this repo (`crates/`) with `time`: the first `sem find` (index not built yet) took 185ms; the second call against the same repo, once the index existed, took 7ms. Run it yourself; the exact numbers will depend on your machine and repo size. The point is the cold-vs-warm gap: no daemon needs to stay alive for the warm number to hold.\n\n### sem graph\n\nPrints the full entity dependency graph for the current repo, or `--json` for the underlying edge list (the same graph `sem impact` and `sem context` are built on top of):\n\n```bash\nsem graph\nsem graph --json\n```\n\n### sem stats\n\nLocal, cumulative counters: how many diffs `sem` has run in this environment and how much of that was noise filtered out. Nothing here leaves your machine (see [Telemetry](#telemetry)):\n\n```bash\nsem stats\n```\n\n## Use as default Git diff\n\nReplace `git diff` output with entity-level diffs. Agents and humans get sem output automatically without changing any commands.\n\n```bash\nsem setup\n```\n\nNow `git diff` shows entity-level changes instead of line-level. No prompts, no agent configuration needed. Everything that calls `git diff` gets sem output automatically. Also installs a pre-commit hook that shows entity-level blast radius of staged changes.\n\nOn macOS and Linux, `sem setup` also registers a Claude Code `UserPromptSubmit` hook (`sem hook prompt-submit`) for prompt-time context injection. It edits `~/.claude/settings.json` idempotently, backs it up first, and leaves any hooks you already have untouched.\n\nTo disable and go back to normal git diff (also removes the session hooks):\n\n```bash\nsem unsetup\n```\n\n## Entity-level diffs on every pull request\n\nAdd the GitHub Action and every PR gets one sticky comment showing which\nfunctions, classes, and methods changed. It updates in place on each push and\ncalls out cosmetic-only PRs (formatting/comments) explicitly:\n\n```yaml\n# .github/workflows/entity-diff.yml\nname: Entity diff\non: pull_request\npermissions:\n contents: read\n pull-requests: write\njobs:\n entity-diff:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: Ataraxy-Labs/sem/action@v0.23.1\n```\n\nNo config, no API keys, never fails your build. See [action/](action/) for details.\n\n## Cloud acceleration (for scale and teams)\n\nLocal is always free and always fast: the on-disk index answers day-to-day queries in single-digit milliseconds even from a cold process, so there's nothing to keep warm and no login required. You do not pay to make your laptop fast.\n\nCloud is for what a laptop can't do. On a very large monorepo the first local graph build can take a few seconds; a shared team graph shouldn't be rebuilt per developer; and CI wants the graph without checking anything out. `sem login` connects those cases to sem cloud, which keeps a warm, pre-built graph for your registered repos and serves the heavy queries from it instead of rebuilding locally.\n\n```bash\nsem login # GitHub device flow, one time\nsem impact myFunc --file src/foo.rs # served from the cloud's warm graph\n```\n\nIt is fully optional and transparent:\n\n- Not logged in, or the cloud is unreachable? sem computes locally and prints the exact same output. No failures, no difference in results.\n- `SEM_LOCAL=1` forces local computation even when logged in.\n- Small repos see no change, local is already fast. The win is for large codebases where rebuilding the graph each time is the bottleneck.\n\nRelated commands, all cloud-account scoped:\n\n```bash\nsem logout # log out\nsem whoami # show current cloud identity\nsem cloud status # cloud + telemetry state for this repo (offline; sends nothing)\nsem cloud enable # turn on cloud queries for a public repo (shows what's sent first)\nsem cloud share # same, with extra confirmation, for a private repo\nsem cloud forget # delete this repo's cloud index and unregister it\nsem xref --json # cross-repo dependencies across your indexed repos\nsem repos # where your code is stored: cloud-indexed repos + local caches\n```\n\n`sem cloud --help` lists every subcommand (`list`, `preview`, `log`, `never` included); each one is read-only or requires explicit confirmation before it sends anything.\n\nIf your team runs code review through sem cloud, `sem review listen ` execs a coding agent pre-configured to join that review as a live listener that answers reviewer questions anchored to specific lines of the diff.\n\n## What it parses\n\n32 programming languages with full entity extraction via tree-sitter:\n\n| Language | Extensions | Entities |\n|----------|-----------|----------|\n| TypeScript | `.ts` `.tsx` `.mts` `.cts` | functions, classes, interfaces, types, enums, exports |\n| JavaScript | `.js` `.jsx` `.mjs` `.cjs` `.es6` | functions, classes, variables, exports |\n| Python | `.py` `.pyi` | functions, classes, decorated definitions |\n| Go | `.go` | functions, methods, types, vars, consts |\n| Rust | `.rs` | functions, structs, enums, impls, traits, mods, consts |\n| Java | `.java` | classes, methods, interfaces, enums, fields, constructors |\n| C | `.c` `.h` | functions, structs, enums, unions, typedefs |\n| C++ | `.cpp` `.cc` `.cxx` `.hpp` `.hh` `.hxx` | functions, classes, structs, enums, namespaces, templates |\n| C# | `.cs` | classes, methods, interfaces, enums, structs, properties |\n| Ruby | `.rb` | methods, classes, modules |\n| PHP | `.php` `.inc` `.phtml` `.module` | functions, classes, methods, interfaces, traits, enums |\n| Swift | `.swift` | functions, classes, protocols, structs, enums, properties |\n| Elixir | `.ex` `.exs` | modules, functions, macros, guards, protocols |\n| Bash | `.sh` | functions |\n| Fish | `.fish` | functions |\n| Lua | `.lua` | functions (global, local, table, and method forms) |\n| HCL/Terraform | `.hcl` `.tf` `.tfvars` | blocks, attributes (qualified names for nested blocks) |\n| Kotlin | `.kt` `.kts` | classes, interfaces, objects, functions, properties, companion objects |\n| Fortran | `.f90` `.f95` `.f03` `.f08` `.f` `.for` | functions, subroutines, modules, programs |\n| Vue | `.vue` | template/script/style blocks + inner TS/JS entities |\n| XML | `.xml` `.plist` `.svg` `.csproj` + 9 more MSBuild/resource extensions | elements (nested, tag-name identity) |\n| ERB | `.erb` `.html.erb` | blocks, expressions, code tags |\n| Svelte | `.svelte` `.svelte.js` `.svelte.ts` (+ `.test`/`.spec` variants) | component blocks + rune JS/TS modules |\n| Perl | `.pl` `.pm` `.t` | subroutines, packages |\n| Dart | `.dart` | classes, mixins, extensions, enums, type aliases, functions |\n| OCaml | `.ml` `.mli` | values, modules, types, classes, externals |\n| Scala | `.scala` `.sc` `.sbt` `.kojo` `.mill` | classes, objects, traits, enums, functions, vals, extensions |\n| Nix | `.nix` | bindings, inherit declarations |\n| Haskell | `.hs` | functions, signatures, data types, newtypes, classes, instances, type synonyms |\n| Elm | `.elm` | value declarations, type aliases, type declarations, port annotations, infix declarations |\n| Clojure | `.clj` `.cljs` `.cljc` | vars, functions, macros, multimethods, protocols, records, types |\n| D | `.d` `.di` | modules, functions, classes, structs, interfaces, unions, enums, templates, aliases, unittests |\n| Zig | `.zig` | functions, tests, variables |\n| SQL | `.sql` `.psql` `.pgsql` `.ddl` | tables, views, functions, indexes, types, schemas, triggers, sequences |\n\nPlus structured data formats:\n\n| Format | Extensions | Entities |\n|--------|-----------|----------|\n| JSON | `.json` | properties, objects (RFC 6901 paths) |\n| YAML | `.yml` `.yaml` | sections, properties (dot paths) |\n| TOML | `.toml` | sections, properties |\n| EDN | `.edn` | top-level map entries (keyword keys) |\n| CSV | `.csv` `.tsv` | rows (first column as identity) |\n| Markdown | `.md` `.mdx` | heading-based sections |\n| LaTeX | `.tex` `.latex` `.cls` `.sty` | sections (part/chapter/section/…), plus theorem/lemma/proof/figure/table/algorithm and other tracked environments |\n\nEverything else falls back to chunk-based diffing.\n\n### Custom extensions and extensionless files\n\nFor files with non-standard extensions, create a `.semrc` in your project root:\n\n```\n.xyz = cpp\n.j = json\n.mypy = python\n```\n\nsem also reads `.gitattributes` patterns (`diff=` and `linguist-language=`) if you already have those set up. `.semrc` takes priority when both define the same extension.\n\nFor files with no extension at all, sem detects the language automatically from content (shebang lines, vim modelines, and structural heuristics like `package`/`import`/`use` statements). This covers 30+ languages with no config needed.\n\n## How matching works\n\nThree-phase entity matching:\n\n1. **Exact ID match**: same entity in before/after = modified or unchanged\n2. **Structural hash match**: same AST structure, different name = renamed or moved (ignores whitespace/comments)\n3. **Fuzzy similarity**: >80% token overlap = probable rename\n\nThis means sem detects renames and moves, not just additions and deletions. Structural hashing also distinguishes cosmetic changes (whitespace, formatting) from real logic changes.\n\n## Use with AI agents (MCP)\n\n`sem mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io) server over stdin/stdout. It's not a command you run and read yourself: it's a server your coding agent launches in the background so it can ask sem questions while it works. That's the reason `mcp` lives alongside the normal commands. The agent gets 8 entity-level tools mirroring the CLI: `sem_entities`, `sem_diff`, `sem_blame`, `sem_impact`, `sem_log`, `sem_context`, `sem_find`, `sem_grep`. (If you're also using sem cloud for code review, four more tools let an agent attach to a review and answer reviewer questions in a loop: `join_review`, `wait_for_branch`, `reply_to_branch`, `list_open_branches`.)\n\nWhy an agent wants these: instead of reading whole files and burning tokens, it can ask \"what breaks if I change `submitOrder`\" (`sem_impact`) or \"give me just the context to refactor this function\" (`sem_context`, which returns the function's source plus its callers and callees) and get a precise, deterministic answer from the dependency graph instead of a grep result that might miss a caller.\n\nAdd it once, then talk to your agent normally. It calls the tools on its own.\n\n**Claude Code:**\n\n```bash\nclaude mcp add sem -- sem mcp\n```\n\nOr one command that also installs the skill, so the agent knows *when* to reach for sem:\n\n```bash\nnpx @ataraxy-labs/sem-skill\n```\n\n**Cursor, Claude Desktop, or any client with an `mcpServers` config:**\n\n```json\n{\n \"mcpServers\": {\n \"sem\": {\n \"command\": \"sem\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\nIf `sem` isn't on the agent's PATH, use the absolute path to the binary. No separate install is needed: `sem mcp` ships in the same binary as every other command.\n\n## JSON output\n\n```bash\nsem diff --format json\n```\n\nReal output, from a one-line logic change to a Python function:\n\n```json\n{\n \"summary\": {\n \"fileCount\": 1,\n \"added\": 0,\n \"modified\": 1,\n \"deleted\": 0,\n \"moved\": 0,\n \"renamed\": 0,\n \"reordered\": 0,\n \"binary\": 0,\n \"orphan\": 0,\n \"total\": 1\n },\n \"changes\": [\n {\n \"entityId\": \"auth.py::function::authenticate_user\",\n \"changeType\": \"modified\",\n \"entityType\": \"function\",\n \"entityName\": \"authenticate_user\",\n \"startLine\": 1,\n \"endLine\": 6,\n \"oldStartLine\": 1,\n \"oldEndLine\": 4,\n \"oldEntityName\": null,\n \"filePath\": \"auth.py\",\n \"oldFilePath\": null,\n \"oldParentId\": null,\n \"beforeContent\": \"def authenticate_user(username, password):\\n if not username or not password:\\n return False\\n return check_credentials(username, password)\",\n \"afterContent\": \"def authenticate_user(username, password):\\n if not username or not password:\\n return False\\n if not check_credentials(username, password):\\n return False\\n return True\",\n \"commitSha\": null,\n \"author\": null,\n \"structuralChange\": true\n }\n ],\n \"binaryChanges\": []\n}\n```\n\nThe named change-type buckets (`added`, `modified`, `deleted`, `moved`, `renamed`, `reordered`) always sum to `total`. `orphan` is a cross-cutting metadata count for module-level changes, and those changes are already included in the named change-type buckets. `beforeContent`/`afterContent` carry the entity's full source on either side of the change; `structuralChange` is `false` when the diff is cosmetic only (whitespace, comments).\n\n## As a library\n\nsem-core can be used as a Rust library dependency, from [crates.io](https://crates.io/crates/sem-core):\n\n```toml\n[dependencies]\nsem-core = \"0.23\"\n```\n\nUsed by [weave](https://github.com/Ataraxy-Labs/weave) (semantic merge driver) and [inspect](https://github.com/Ataraxy-Labs/inspect) (entity-level code review).\n\n## Architecture\n\n- **tree-sitter** for code parsing (native Rust, not WASM)\n- **git2** for Git operations\n- **rayon** for parallel file processing\n- **xxhash** for structural hashing\n- A per-repo cache directory (SQLite entity cache + an mmap-able query index) backs `find`/`callers`/`refs`/`grep` with cold-process lookups and no background daemon\n- Plugin system for adding new languages and formats (see [CONTRIBUTING.md](CONTRIBUTING.md))\n\n## Telemetry\n\nLocal by default: sem counts command names (e.g. `diff`, `impact`) on your own machine only, and in that mode nothing is ever uploaded. No code, file paths, repo names, or user identity is recorded, and no network call is made.\n\n```bash\nsem telemetry preview # see current mode and exactly what would be sent\nsem telemetry on # opt in: also upload counts to help improve sem\nsem telemetry off # record nothing at all\n```\n\n`SEM_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` force the record-nothing behavior regardless of mode. Development builds (anything run out of a `cargo build` `target/` directory) never record, so working on sem itself doesn't pollute the numbers.\n\n## Contributing\n\nWant to add a new language? See [CONTRIBUTING.md](CONTRIBUTING.md) for a step-by-step guide.\n\n## Star History\n\n[![Star History Chart](assets/star-history.png)](https://star-history.com/#Ataraxy-Labs/sem&Date)\n\n## License\n\nMIT OR Apache-2.0\n", "bytes": 22996, "sha": "1fcf6533e3b0ed221538176396798eb8444601f0fd74fbb60a5555a31ed8c495", "repo_slug": "ataraxy-labs/sem", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ataraxy_labs_sem_e89725d7/readme" }