Performs local-first change-impact analysis by mapping Git diffs to TypeScript symbols, exported contracts, invariants, and tests to provide safety verdicts.
Also known as hoklims/semctx
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- Apache-2.0
What is semctx MCP?
semctx performs local-first change-impact analysis by mapping Git diffs to TypeScript symbols, exported contracts, invariants, and tests to provide safety verdicts.
Summary generated from the project's README
About semctx MCP server
Developers working on TypeScript repositories can use semctx to perform local-first change-impact analysis. By mapping Git diffs to TypeScript symbols, exported contracts, and existing tests, the tool provides safety verdicts to prevent breaking changes. It operates entirely on your local machine, reading your files and Git history without calling any external LLMs or network services. This makes it a private and fast way to ensure code integrity during development.
To use the tool, you must have Bun 1.4.3 or newer installed. The workflow involves running a setup command to create a local index of your code's structure, followed by verification commands to check uncommitted edits or compare branches. The system issues one of three verdicts: PASS, WARN, or BLOCK. A BLOCK verdict exits with code 3, allowing you to integrate it directly into Git hooks, CI jobs, or coding agents to automatically stop unsafe changes from being merged.
What you can do with it
- 1Enforce critical security invariantsDevelopers can tag specific symbols as security-sensitive to trigger a block if they are modified without verification.
- 2Automate CI safety checksYou can configure your continuous integration pipeline to reject pull requests that violate defined code invariants.
- 3Verify uncommitted local editsBefore committing code, you can check if your current working tree changes impact any declared rules or contracts.
Written from the project's README. Every use case is checked against a quote from it.
How to install semctx MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall semctx MCP in Claude Code
$ claude mcp add semctx -- npx -y semctxInstall semctx MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"semctx": {
"command": "npx",
"args": [
"-y",
"semctx"
]
}
}
}Install semctx MCP in VS Code
.vscode/mcp.json
{
"servers": {
"semctx": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"semctx"
]
}
}
}Install semctx MCP in VS Code CLI
$ code --add-mcp '{"name":"semctx","type":"stdio","command":"npx","args":["-y","semctx"]}'Install semctx MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"semctx": {
"command": "npx",
"args": [
"-y",
"semctx"
]
}
}
}Install semctx MCP in Codex
$ codex mcp add semctx -- npx -y semctxInstall semctx MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.semctx] command = "npx" args = ["-y", "semctx"]
Install semctx MCP in Gemini CLI
$ gemini mcp add -s user semctx npx -- -y semctxInstall semctx MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"semctx": {
"command": "npx",
"args": [
"-y",
"semctx"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablehoklims/semctx is public and reachablegithub.com/hoklims/semctx ↗Pass
- Package names this repository as its sourcesemctx names hoklims/semctx as sourcenpmjs.com/package/semctx ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for semctxnpmjs.com/package/semctx/v/0.4.5#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/hoklims/semctx ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from semctxPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubEnglish · Français
semctx
semctx reads the Git diff of a TypeScript repository and shows which exported contracts, declared rules and tests the change touches. It ends with one verdict, PASS, WARN or BLOCK. By default BLOCK exits with code 3, so a Git hook, a CI job or a coding agent can stop the change.
Analysis runs on your machine. It reads your files and your local Git history, and calls no LLM and no network service. To try it on your own code, start from a clean working tree in a repository with at least one commit (Bun 1.4.3 or newer):
bunx semctx@latest setup # once: config and local index
# ...edit some code...
bunx semctx@latest verify diff # verdict for your uncommitted edits
The quick start shows the branch check that CI runs.
What a verdict looks like
The first-use demo uses a small repository with no tests.
Take it at its first commit, run semctx setup, then make the demo's three edits. One of them adds
a required field to an exported interface in src/cart.ts:
@@ -1,8 +1,9 @@
export interface CartTotal {
subtotalCents: number;
taxCents: number;
+ discountCents: number;
}
-export function computeCartTotal(subtotalCents: number, taxCents: number): CartTotal {
- return { subtotalCents, taxCents };
+export function computeCartTotal(subtotalCents: number, taxCents: number, discountCents: number): CartTotal {
+ return { subtotalCents, taxCents, discountCents };
}
semctx verify diff prints this and exits 0:
Verdict: WARN
range : working tree
changed files : 3
impacted nodes: 7
Impacted contracts
Exported interface "CartTotal" is a public, compiler-enforced contract. [statically_verified]
Recommended tests
none
Unknowns
? Could not confirm index binding (STALE: ANALYSIS_INPUT_MISMATCH, WORKING_DIFF_MISMATCH); impact is reported without a freshness proof.
Findings
[WARN ] contract_changed_without_test: exported contract changed without a covering test: CartTotal
| In the report | What it tells you |
|---|---|
Verdict: WARN |
The answer. WARN is advisory, so the exit code is 0. |
changed files, impacted nodes |
Files in the diff, then the files and declarations whose lines it touches. |
Impacted contracts |
Exported interfaces and type aliases the change edits. |
[statically_verified] |
How semctx knows: read from the code's structure. tested means a test file imports it; inferred means it rests on a marker comment. |
Recommended tests |
Test files that import any symbol declared in a changed file, touched or not. The demo has none. |
? Could not confirm index binding |
The index was built before the edit. Expected when you check uncommitted work. |
[WARN ] contract_changed_without_test |
The rule that fired, and the symbol it fired on. |
computeCartTotal changed as well, but exported functions raise nothing by default: only exported
interfaces and type aliases count as contracts. The other two edits get no finding either. One
rewords a comment, the other slips an off-by-one into an unexported discount helper;
Limits explains why semctx misses that bug. A
public summary of the demo's evidence is published
online; it shows counts and verdicts, not this raw output.
How it works
flowchart LR
diff["Your Git diff<br/>working tree, --staged or --base"] --> map["What it touches<br/>symbols, exported contracts, linked test files"]
map --> rules["Rules<br/>built-in + @invariant, @tag critical, @tag security"]
rules --> verdict{"Verdict"}
verdict -- "exit 0" --> pass["PASS"]
verdict -- "exit 0" --> warn["WARN"]
verdict -- "exit 3" --> block["BLOCK"]
semctx index reads your code with the TypeScript compiler API and stores a graph of symbols,
imports, tests and markers in a local, git-ignored index. verify diff maps the changed lines onto
that graph, applies the rules, and the most severe finding sets the verdict. The exit codes above
are the defaults (--fail-on block).
Quick start
You need Bun 1.4.3 or newer and a Git repository with at least one commit. This
flow checks a committed branch against main, which is also what the GitHub Action does.
-
Set up once, from a clean working tree (commit or stash first):
bunx semctx@latest setup -
Make your change on a branch and commit it:
git switch -c try-semctx # ...edit code... git add -A && git commit -m "my change" -
Index that commit, then check the branch against
main:bunx semctx@latest index bunx semctx@latest verify diff --base main
setup writes .semctx/config.json and six .sem templates in .semctx/semantic/ (comments only
until you write something), updates .gitignore and builds the local index. The config and the
templates are meant to be committed, which step 2 does. Re-running setup is harmless on a clean,
committed tree. It re-indexes, so never run it on uncommitted edits you are about to verify.
On a small repository setup ends with OK ready (analysis partial) and a WARN line on stderr.
That is normal; semctx index-health lists the reasons.
ok config written
ok semantic 6 file(s) scaffolded (.semctx/semantic/, versioned)
·· index analyzing 3 selected file(s) (typescript:3)…
ok index 9 nodes, 9 edges, 1 claims
ok check model consistent
!! analysis partial
TypeScript analysis: 1 worker(s), single
OK ready (analysis partial)
And on stderr:
WARN setup succeeded, but incomplete analysis cannot justify negative conclusions; run 'semctx index-health --json' for the exact gates and reasons.
[!IMPORTANT] The index has to describe committed code. Run
semctx indexagain after every commit, pull or branch switch, otherwiseverify diffanswers BLOCK withindex_binding_stale. For uncommitted work, index a clean tree, edit, then verify without re-indexing in between: re-indexing an edited tree can hide a finding.
--base needs a ref that exists locally, because semctx never fetches. Use your default branch name
if it is not main. To drop the bunx semctx@latest prefix, install the CLI once with
bun add -g semctx@latest. The rest of this README writes plain semctx.
The three verdicts
The exit code depends on --fail-on:
| Verdict | default (--fail-on block) |
--fail-on warn |
--fail-on none |
|---|---|---|---|
| PASS | 0 | 0 | 0 |
| WARN | 0 | 3 | 0 |
| BLOCK | 3 | 3 | 0 |
A run that stops before a verdict, for example with no commit or an invalid option value, exits 1.
An unknown command or subcommand exits 2. --dry-run only resolves the Git range and the options:
it exits 0 when that works, fails like any other run otherwise, and does not load the config, so a
successful dry run says nothing about .semctx/config.json.
These are the rules setup writes to .semctx/config.json, plus one built-in check:
| Rule | Verdict | Fires when |
|---|---|---|
invariant_touched_without_test |
BLOCK | code under an @invariant changes with no covering test |
critical_contract_changed_without_test |
BLOCK | an exported interface or type alias tagged @tag critical or @tag security changes with no covering test |
security_surface_without_verification |
BLOCK | a symbol tagged @tag security changes with no covering test |
contract_changed_without_test |
WARN | any other exported interface or type alias changes with no covering test |
contradiction_unresolved |
WARN | the change touches a document marked contradicted or deprecated |
index_binding_stale |
BLOCK, always | the index was built for a different commit, as after a commit, pull or branch switch (run semctx index). With no index at all, the run stops before a verdict and exits 1 |
To relax a rule, set its severity to warn or remove it
(blocking rules). The GitHub
Action applies such a change only through config-path.
index_binding_stale cannot be configured. Neither can analysis_scope_incomplete, which exists
only with config v2: it blocks when a changed file in scope cannot be analysed, and warns when that
file's analysis is only partial.
What counts as a covering test
semctx never runs your tests. In the default TypeScript-only flow, it checks direct imports under the symbol's declared name:
Import in a test file, with greet declared in src/index.ts |
Covers greet |
|---|---|
import { greet } from "../src/index"; |
yes |
import { greet as subject } from "../src/index"; |
no, aliased |
import * as m from "../src/index"; |
no, namespace import |
import { greet } from "../src/barrel"; where src/barrel.ts re-exports it |
no, re-export |
The opt-in config v2 qualified-static-v1 profile also follows canonical renamed imports,
modeled namespace members and re-exports to their original declarations. These are static test
associations; unknown or unsupported targets do not establish coverage. See the
qualified profile and its
admission contract.
Type-only imports do not count either. A file is a test when its name ends in .test.ts or
.spec.ts (or the .tsx, .mts, .cts variants), when it sits in a test/, tests/ or
__tests__ folder, or when it imports vitest, bun:test or node:test.
Tell semctx what must not break
Without markers in your code, the symbol rules can only raise a WARN, and only for exported
interfaces and type aliases; a changed document marked contradicted or deprecated can also raise a
WARN. The built-in checks still block: index_binding_stale when the index
is out of date, and, with config v2, analysis_scope_incomplete. To make semctx block on your own
rules, write the rule in a one-line JSDoc tag on the code it protects,
as in examples/consumer-typescript-repo:
/**
* @invariant greeting-non-empty: a greeting must never be an empty string
*/
export function greet(name: string): string {
return `Hello, ${name}!`;
}
Commit the marker and run semctx index: rules come from the index, and a working-tree check reads
the index built before your edit. Then change the body of greet while no test imports it:
- return `Hello, ${name}!`;
+ return name.length > 0 ? `Hello, ${name}!` : "";
verify diff exits 3, and the report contains (excerpt):
Impacted invariants
! a greeting must never be an empty string [inferred]
Findings
[BLOCK] invariant_touched_without_test: invariant-constrained code changed without a covering test: greet
This edit really breaks the rule: it returns an empty string for an empty name. semctx cannot see
that. It sees that guarded code changed with no test behind it, and stops the change until a test
exists. To clear the finding, add one that imports greet from the file that declares it:
// test/greet.test.ts
import { expect, test } from "bun:test";
import { greet } from "../src/index";
test("a greeting is never empty", () => {
expect(greet("")).not.toBe("");
});
Commit the code and the test, run semctx index, then semctx verify diff --base main. The finding
clears and test/greet.test.ts appears under Recommended tests. Run that test yourself: here it
fails, and that failure is what tells you the rule is broken.
Markers go directly above the declaration they guard:
| Declaration | Marker recognised |
|---|---|
function, or const/let holding an arrow function or function expression |
yes |
| class, interface, type alias, enum | yes |
| method, class property, plain constant | no, silently ignored; mark the class to guard its methods |
@tag security on a declaration the table recognises, or @tag critical on an exported interface or type alias, arms the two
other BLOCK rules. @tag critical on a function arms nothing. semctx only uses markers you write
and never adds any. A marker must fit on one line.
Where it runs
| Surface | Start with | What you get | Guide |
|---|---|---|---|
| CLI | semctx verify diff |
The verdict as text, GitHub annotations (--format github) or a versioned JSON report (--format json) |
CLI reference |
| GitHub Actions | uses: hoklims/semctx/packages/github-action@v0.4.5 |
An annotation at each symbol a finding names, a job summary and a verdict output; BLOCK fails the job |
GitHub Actions |
| Claude Code | bunx semctx@latest install |
The semctx MCP tools and skills, plus an optional guarded mode that holds git commit until the diff is verified |
Claude Code |
| Codex | bunx semctx@latest install --host codex |
The same MCP tools and skills | Codex |
| Any MCP client | tool semctx_verify_change |
The same diff check over MCP, next to the server's other typed tools | MCP setup |
GitHub Actions
Copy examples/github-actions/semctx.yml to
.github/workflows/, or let semctx setup --preset github-claude write it:
name: Semctx
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
jobs:
semctx:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # semctx needs the merge base and never fetches
- uses: hoklims/semctx/packages/github-action@v0.4.5
with:
base: ${{ github.event.pull_request.base.sha }}
head: ${{ github.sha }}
fail-on: block
The action installs Bun itself, indexes the checked-out commit and verifies the pull request range.
WARN fails the job only with fail-on: warn. It needs no secrets and posts no PR comments, and it
never loads bunfig.toml or .env from the pull request, so a PR cannot run code on the runner
that way. Pin a release tag, because main and stable move.
The action starts from the default config, not the one committed in .semctx/. To apply your own
rules, keep a copy outside .semctx/ and pass it as config-path
(custom config).
The demo's WARN, printed with semctx verify diff --format github:
::warning title=semctx%3A contract_changed_without_test,file=src/cart.ts,line=1::exported contract changed without a covering test: CartTotal
::notice::semctx verdict WARN — 0 block, 1 warn (range working tree)
Claude Code and Codex
Run bunx semctx@latest install from the repository you want to check. It installs or updates the
semctx plugin for each detected host (Claude Code or Codex must already be installed), then runs
setup. --dry-run previews the plan, --host codex|claude|all picks the hosts, and
--skip-setup installs for the machine only. Re-running it is harmless on a clean, committed tree;
because it runs setup, which re-indexes, add --skip-setup when you have uncommitted edits.
The plugins give the agent the semctx MCP tools and skills, for example semctx_verify_change to
check its own diff before it says it is done. The plugin hooks run on Node, so Node must be on your
PATH too.
By default the plugins only report. On Claude Code, a .semctx/guard.json containing
{"enabled": true} turns on guarded mode:
git commit and git push are refused until semctx verify diff --record has recorded a non-BLOCK
verdict for exactly that content. With nothing recorded, the hook answers
semctx guarded mode: no verification on record. Set SEMCTX_GUARD=off to turn the mode off.
Codex has no guarded mode. When the Codex agent runs semctx from the shell, it calls a global
semctx, so install one with bun add -g semctx@latest.
Plugins update from the stable branch, which moves only when a release is published to npm.
semctx plugin-status shows the version you have.
Semctx 0.4.5 requires Bun >=1.4.3.
The supported, tested host baseline is Codex 0.147.0 and
Claude Code 2.1.229. Other host versions are unknown until tested;
these pins do not claim the earliest historically compatible versions.
Baseline delivery evidence.
Installation does not reload an active session: open a new Codex task, or run
/reload-plugins in Claude Code (restart if reload fails).
Other MCP clients
Other MCP clients can run the server from a source checkout
(config snippet). The server registers
39 schema-declared tools (typed inputs and outputs), listed in
tool-contract.ts. Tools that read a repository take
its absolute path as repositoryRoot. SEMCTX_ROOT, if set, must be absolute.
Limits
semctx reads your code. It never builds it and never runs your tests, so treat a report as a list of what to re-check.
- A behaviour change inside a function gives no finding unless a marker covers it. In the demo, the
off-by-one in
src/pricing.tsis a real bug and gets no finding, because nothing marks that code. - An empty report does not prove that nothing was affected. When the index reports
analysis partial, as it does on the demo, semctx does not claim it found every reference to your code. Calls that cannot be resolved statically are left out, runtime behaviour such as races is out of reach, andUnknownslists only a few known gaps. - It sees what
git diffsees. Untracked files are ignored until yougit addthem (git add -Nis enough). Working-tree and--stagedchecks also skip symbols declared in a brand-new file: commit, index and use--baseto check those. verify diff --from-file <patch>always returns BLOCK withindex_binding_stale, because a patch file does not record which commit it came from. Verify changes in the repository itself.- Languages: TypeScript (
.ts,.tsx,.mts,.cts) by default; declaration files (.d.ts) are skipped, so a changed public declaration there raises nothing. Python through 3.12 is opt-in with config v2 (semctx setup --polyglot) and limited to modules, classes, functions, imports and markers, with no calls and no test links. Markdown and SQL files are only classified as documents and migrations. Files in other languages are skipped unless config v2 selects them: a selected file that no analyzer supports makesverify diffBLOCK withanalysis_scope_incompletewhen it changes. - Links from
.semfiles name a file and a symbol, so renaming either can mark them stale.semctx migrate anchors --applyrewrites older links that still carry line numbers. - It does not search code or pick the files an agent should read. Grep and embedding search do that better (ADR 0005).
Current delivery status
semctx is pre-1.0 (0.4.x). The CLI, both plugins and the GitHub Action share one version and ship together from one release tag. Pin an exact version when you need reproducible results. Minor releases can still contain breaking changes; the changelog lists them.
| Status | What |
|---|---|
| Released | verify diff, impact diff, the GitHub Action, the Claude Code and Codex plugins, the MCP server, change records and the planning tools |
| Opt-in | config v2 (setup --polyglot) and guarded mode on Claude Code |
| Experimental | the Oh My Pi package, context prepare (semctx_prepare_task over MCP), and bench (ContextPack regression scoring); Grok can load the Claude Code plugin but is outside the tested host baseline |
| Partial | agent checkpoints, of which only before_completion is automated (reference, #28) |
| Withdrawn | the task-to-files retriever, which lost to plain BM25 search (ADR 0005, results); context prepare is what is left of it |
| Not built | anything that applies a plan for you |
| Not measured | accuracy: the public replay corpus has 30 real changes, none with a known expected result yet, so none is scored |
The private workspace package @semantic-context/experimental-context-pack-eval (in
packages/eval, formerly @semantic-context/eval) backs bench. It scores experimental
ContextPack regression expectations; it does not evaluate code-search effectiveness or
verify diff. Task frames remain available for task/plan reconciliation.
Planned work is in the roadmap.
semctx MCP questions
How do I add semctx MCP to Claude Code?
Run claude mcp add semctx -- npx -y semctx in your terminal. Add --scope user to make it available in every project.
How do I add semctx MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does semctx use LLMs or network services?
No, the analysis runs entirely on your local machine and does not call any LLM or network service.
What are the possible verdicts from semctx?
The tool provides three verdicts: PASS, WARN, or BLOCK, which correspond to different exit codes.
How can I make semctx block on specific code changes?
You can use JSDoc tags like @invariant, @tag critical, or @tag security on the code you want to protect to trigger blocking verdicts.
Does semctx run my tests?
No, semctx does not execute your tests; it only checks if test files import the symbols being changed.