sem - Semantic Version Control Tool

The sem CLI provides entity-level diffs for Git, focusing on code structures like functions, classes, and methods rather than raw lines. Available commands include:

• sem diff: Semantic diff of changes.
• sem graph: Visualize the dependency graph.
• sem impact: Analyze the impact of changes.
• sem blame: Semantic code blame.

The sem storage engine manages three distinct axes to prevent re-computation and optimize performance for agents:

By addressing space, time, and attention, sem ensures that computations like parsing, history walking, and context filling are paid for only once.

To build the sem binary from the Rust source code, use cargo build with the --release flag. The resulting binary will be located in target/release/sem.

# Build the release binary
cargo build --release
# Binary at target/release/sem

Use the scripts/large-js-fixture.mjs script to generate a repeatable TypeScript/JavaScript fixture for testing graph-build performance. The generator creates a standalone fixture root containing src/, package.json, tsconfig.json, fixture-manifest.json, and a marker file.

Note: Existing marked fixture roots are replaced for repeatability. Non-empty unmarked directories will be refused unless the --force flag is used.

node scripts/large-js-fixture.mjs \
  --out /tmp/sem-large-js-fixture \
  --files 1000 \
  --entities-per-file 12 \
  --fanout 5 \
  --import-style-mix named:3,default:1,namespace:1,type:1 \
  --nested-depth 3 \
  --body-lines 40 \
  --language mixed

To extend sem with support for a new language, follow these steps:

1. Add the required tree-sitter grammar to sem-core/Cargo.toml.
2. Create a new parser plugin in sem-core/src/parser/plugins/.
3. Register the new plugin in sem-core/src/parser/mod.rs.
4. Add corresponding tests.

For the complete 7-step implementation guide, refer to CONTRIBUTING.md.

Add the GitHub Action to your workflow to automatically comment on Pull Requests with a summary of changed entities (functions, classes, methods). It also identifies cosmetic-only PRs (formatting/comments).

Workflow Example:

name: Entity diff
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  entity-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Ataraxy-Labs/sem/action@v0.15.1

The sem mcp command starts a Model Context Protocol (MCP) server over stdin/stdout. This allows coding agents to use 6 entity-level tools: sem_impact, sem_context, sem_diff, sem_entities, sem_blame, and sem_log.

Claude Code

To add sem to Claude Code:

claude mcp add sem -- sem mcp

To install the skill so the agent knows when to use it:

npx @ataraxy-labs/sem-skill

Cursor, Claude Desktop, or other MCP clients

Add the following to your mcpServers configuration. If sem is not in your PATH, use the absolute path to the binary:

{
  "mcpServers": {
    "sem": {
      "command": "sem",
      "args": ["mcp"]
    }
  }
}

You can install sem using several methods depending on your environment:

• Shell script: curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh
• Homebrew (macOS): brew install sem-cli
• Windows (winget): winget install AtaraxyLabs.sem
• npm (Node.js): npm install --save-dev @ataraxy-labs/sem
• Bun:

  bun add -d @ataraxy-labs/sem
  bun pm trust @ataraxy-labs/sem

• Cargo (Rust source): cargo install --git https://github.com/Ataraxy-Labs/sem sem-cli
• Docker:

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