Sem Integration

sem Integration

Foundation patterns for using sem semantic diffs in night-market skills.

When To Use

Consult this skill when building or modifying skills that consume git diff output. It provides the detection, installation, and fallback patterns.

When NOT To Use

• Direct sem CLI usage (just run sem diff yourself)
• Skills that don't consume diff output

Detection Pattern

Check sem availability once per session:

# Detection (cache per session)
_sem_check() {
  local cache="${CLAUDE_CODE_TMPDIR:-/tmp}/sem-available"
  if [ -f "$cache" ]; then
    cat "$cache"
    return
  fi
  if command -v sem &>/dev/null; then
    echo "1" | tee "$cache"
  else
    echo "0" | tee "$cache"
  fi
}

When _sem_check returns 0, offer installation. See modules/detection.md for install-on-first-use logic and platform-specific commands.

Semantic Diff Pattern

Primary path (sem available):

sem diff --format json <baseline>

Fallback path (sem unavailable):

git diff --name-only --diff-filter=A <baseline>
git diff --name-only --diff-filter=M <baseline>
git diff --name-only --diff-filter=D <baseline>
git diff --name-only --diff-filter=R <baseline>

See modules/fallback.md for output normalization that produces the same entity schema from both paths.

Impact Analysis Pattern

Primary path (sem available):

sem impact --json <file-or-entity>

Fallback path (sem unavailable): use rg/grep to trace callers by filename. See modules/fallback.md.

sem Detection and Installation

Detection Logic

1. Check session cache at $CLAUDE_CODE_TMPDIR/sem-available 2. If cache exists, use cached value 3. If no cache, run command -v sem 4. Write result to cache

Install-on-First-Use

When sem is not detected, present installation options in priority order:

Rust toolchain (preferred, works on all platforms):

cargo install --locked sem-cli

macOS (Homebrew, if formula exists):

brew search sem-cli && brew install sem-cli

Note: the Homebrew formula may not exist. If brew search returns no results, fall back to cargo install above.

Linux (binary download):

mkdir -p ~/.local/bin && curl -fsSL https://github.com/Ataraxy-Labs/sem/releases/latest/download/sem-x86_64-unknown-linux-gnu -o ~/.local/bin/sem && chmod +x ~/.local/bin/sem

Prompt Template

When sem is missing, say:

sem (semantic diff tool) can provide entity-level diffs

instead of line-level diffs. Install it?

>

- cargo install --locked sem-cli (any platform with Rust)

- brew install sem-cli (macOS, if formula available)

- Linux binary: `mkdir -p ~/.local/bin && curl -fsSL

https://github.com/Ataraxy-Labs/sem/releases/latest/download/sem-x86_64-unknown-linux-gnu

-o ~/.local/bin/sem && chmod +x ~/.local/bin/sem`

- Or skip to use standard git diff

If the user declines, write 0 to the cache and proceed with fallback for the rest of the session.

Cache Invalidation

The cache file is in $CLAUDE_CODE_TMPDIR which is per-session. No explicit invalidation needed: each new Claude Code session starts fresh.

Fallback Output Normalization

When sem is unavailable, produce entity-like output from standard git commands.

Entity Schema

sem produces raw output with these fields:

{
  "entityId": "module::Class.method",
  "entityType": "function|class|method",
  "entityName": "method",
  "changeType": "added|modified|deleted|renamed",
  "filePath": "path/to/file.py"
}

The normalization layer maps these to a common schema used by consumer skills:

{
  "name": "entity_or_filename",
  "kind": "function|class|file",
  "change_type": "added|modified|deleted|renamed",
  "file": "path/to/file.py"
}

Mapping: entityName to name, entityType to kind, changeType to change_type, filePath to file. Fallback uses file as the kind since git diff operates at file level.

Fallback Commands

# Collect changes by type
added=$(git diff --name-only --diff-filter=A <baseline>)
modified=$(git diff --name-only --diff-filter=M <baseline>)
deleted=$(git diff --name-only --diff-filter=D <baseline>)
renamed=$(git diff --name-only --diff-filter=R <baseline>)

Entity Extraction from Diff Hunks

For richer fallback (optional), parse diff hunks for function/class definitions:

# Extract added functions from diff (includes async def)
git diff <baseline> | grep -E '^\+(async )?def |^\+class ' | \
  sed 's/^+//' | sed 's/(.*//'

This gives function-level granularity without sem, though it misses renames, decorated definitions, and cross-file dependencies.

Impact Fallback

When sem impact is unavailable, trace callers with rg:

# For each changed file, find importers
git diff --name-only HEAD | while read f; do
  module=$(basename "$f" .py)
  if command -v rg &>/dev/null; then
    rg -l "import.*$module|from.*$module" --type py .
  else
    grep -rl "import.*$module\|from.*$module" \
      --include="*.py" .
  fi
done | sort -u