sem

sem parses 30+ languages with tree-sitter and answers questions about entities (functions, classes, methods) and the calls between them. Instead of "lines 43-51 changed" it says "function validateToken in src/auth.ts was modified, and these 3 callers and 2 tests reach it". It works in any Git repo with no setup. Answers are deterministic; when a caller set may be incomplete, sem says so.

Four questions, four verbs

| Question | CLI | MCP tool | |---|---|---| | Where is it? | sem find NAME, sem grep TEXT | sem_find, sem_grep | | What does my change touch? | sem impact NAME, sem impact --diff HEAD --tests | sem_impact | | Is it correct? | sem check | sem_check | | What should a human review? | sem certify main..HEAD | sem_certify |

Also: sem diff (which entities changed), sem graph (how the code is connected), sem history (how an entity changed; --blame for a file). Every verb takes --json.

Use the MCP tools first

If the agent has the sem MCP server (tools named mcp__sem__*), call those instead of running sem in a shell. They return compact results and carry elapsed_ms. If they are deferred, load them first rather than falling back to Bash.

| Task | MCP call | |---|---| | where is X defined | sem_find with query: "X" | | read and understand X | sem_find with query: "X", mode: "context": body plus callers and callees, one call, no file needed | | who calls X | sem_find with mode: "callers" | | what X calls | sem_find with mode: "refs" | | what is in this file or directory | sem_find with in: "src/auth.ts" | | find code by intent, name unknown | sem_find with intent: "where retries are scheduled" | | a string, error message, config key | sem_grep, or sem_find with text (hits named by entity) | | what breaks / which tests to run | sem_impact (mode: "tests" for tests only) | | is the change correct | sem_check | | what to review in a range | sem_certify with range: "main..HEAD" | | what changed | sem_diff | | how X evolved / who changed it | sem_history (blame: true with file_path for a file) |

When you know or can guess the name, one sem_find call with mode context replaces a grep followed by a file read. Ambiguous names return a short candidate list; pass in only then.

CLI

# where is it?
sem find validateToken                  # definition: type name file:line
sem find validateToken --callers        # who calls it
sem find validateToken --refs           # what it calls
sem find validateToken --context        # its code plus callers and callees, token-budgeted
sem find validateToken --context --budget 4000 --hops 1
sem find --in src/auth.ts               # every entity in a file or directory
sem grep "token expired"                # text, rg-style file:line:text

# what does my change touch?
sem impact validateToken                # dependents, deps, transitive impact, tests
sem impact validateToken --tests        # only the tests to run
sem impact --diff HEAD --tests          # tests for the uncommitted change
sem impact --diff main..HEAD --json     # one report per changed entity

# is it correct?
sem check                               # the project's compiler, type checker, linter, tests: exit 0 pass, 1 fail, 2 could not decide
sem check --checkers ts,tests           # only these checkers

# what should a human review?
sem certify main..HEAD                  # review certificate (markdown)
sem certify main..HEAD --arch           # the architecture view
sem certify main..HEAD --json

# more
sem diff                                # working tree changes, by entity
sem diff --from HEAD~5 --to HEAD --format json
sem graph --json                        # entity graph; --modules, --dataflow, --system for other layers
sem history validateToken               # how it evolved
sem history --blame src/auth.ts         # who last changed each entity

Older names (sem callers, sem context, sem entities, sem log, sem blame, sem arch-diff, sem topology, ...) still work with the same output.

Draw the blast radius in your reply

When an impact result drives your answer (a refactor decision, a "what breaks" question), render it as a small ASCII tree in the response:

◉ validateToken · src/auth.ts
│  8 direct → 23 transitive
├─▶ refreshToken        src/auth.ts
├─▶ loginHandler        src/routes/login.ts
├─▶ SessionMiddleware   src/middleware/session.ts
╰─▶ … +5 more (12 tests)

Real callers first, tests collapsed into a count, no invented entries: draw only what the tool returned. Skip the drawing when impact was incidental.

Make the leverage felt

sem_find (context mode) and sem_impact return elapsed_ms. When one sem call replaces several grep/read steps, or catches something text search cannot (a transitive caller in another file), say so in one terse clause, e.g. (sem_impact: 9ms, 2 transitive callers grep would miss). Once per non-obvious win, never a sales pitch. If you fall back to grep or a file read on a structural question, say why.

Install check

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.