Code Guardian

code-guardian

Status: active development -- changelog

mcp-name: io.github.LuminariSoftwares/code-guardian

0 FAIL findings on 8 of 8 clean, well-known repositories, scanned without running them.

A deterministic A-F grade for any repo -- is it safe to run, will it work, is it complete -- for people about to run code they did not write.

Quick start (60 seconds)

From a clean Python 3.11+ environment (no other dependencies):

pip install code-guardian-mcp

code-guardian scan /home/user/project # the grade, every finding with file:line; exit 0, 1 or 3 code-guardian plan /home/user/project --top 3 # the three fixes worth the most Overall points

Success looks like a first line code-guardian 0.6.0 scan of , then a status: COMPLETE line and four score lines. On a one-file project it takes well under a second. To give the same tools to an AI client, add the MCP server (see MCP server for Claude Desktop and other clients):

claude mcp add code-guardian -- uvx code-guardian-mcp mcp

Proof

Run on 2026-11-05 from a fresh clone of the v0.6.0 tag, with code-guardian-mcp==0.6.0 installed from PyPI:

python tools/calibrate.py

Result: 0 FAIL findings on 8 pinned repositories (5 well-known Python projects and 3 sibling guardians).

python -m pytest -q

1386 passed, 82 skipped in 147.56s (0:02:27)

Caveat: this is static analysis. A grade A is "nothing the scanners recognise", not "proven safe". Python is analysed in full, JavaScript and TypeScript at token level, and every other language gets the secret scan and the repo-hygiene checks only.

Before you run a repository you did not write, or merge a change an AI assistant made, you want to know whether it is dangerous, whether it is broken and what is missing. code-guardian answers that from the source alone, in one command that tells you three things about any repo without running it:

• Safe: is it safe to run?
• Works: will it work?
• Complete: does it have what it needs?

Each is a score out of 100 (higher is better), combined into an Overall score and an A–F grade. Scores come only from deterministic checks with fixed weights: same repo, same version, same output, every time. On top of that:

• Orphan code: functions, classes and modules nothing reachable from the project's entry points uses, judged against a small goal contract.
• An optional plain-English explanation from a local model, which never adds, removes or rescores a finding.
• A verify loop for AI-assisted changes: run it before and after every change to learn what the change fixed, what it broke, what to fix next, and whether the scan itself can be trusted (see The verify loop).

It parses the code (ast for Python; a small lexer for JavaScript and TypeScript; json, tomllib and configparser for manifests; regular expressions for secrets) and never executes, imports or installs it. A scan makes no network calls. Python 3.11+, standard library only.

One of four free, MIT-licensed guardians for people running local models, each answering one question from the outside: tool-guardian (what do my tools cost the window?), context-guardian (will this session hit the limit?), stack-guardian (is my stack healthy?), code-guardian (is this code safe to run?).

Who it is for. Anyone running local AI models, or code an AI assistant wrote, on their own machine: you cloned a repository, or an assistant just rewrote a module, and you want a verdict before you run it. It is the fourth of four free, MIT-licensed guardians, each answering one question about a local setup from the outside:

Install it as `code-guardian-mcp`; code-guardian on PyPI is an unrelated project by someone else. You get a CLI, a GitHub Action, a pre-commit hook and an MCP server. The MCP side is a hand-written stdio server speaking MCP protocol 2024-11-05 — no SDK, no dependencies (see ADR 0003) — and it is stdio only: to reach it over a network, put an authenticating proxy in front of it rather than exposing the process. One maintainer, best effort: issues and pull requests get a reply when evenings allow, and there is no paid support (CONTRIBUTING.md, SECURITY.md).

What it analyses

Python is analysed in full, JavaScript and TypeScript at token level, and every other language gets the secret scan and the repo-hygiene checks only. Every report prints a coverage: line saying which files were analysed and how, e.g. coverage: 40 Python analysed; 112 JavaScript/TypeScript analysed (token level); 9 .go secret-scan only, and coverage.languages in the JSON gives the same with the checks that ran.

What "token level" means. A lexer cuts each JavaScript or TypeScript file into tokens, telling strings, template literals, comments, regular expressions and JSX text from code, so a sink named in a string or a comment is never a finding. It is a lexer, not a parser: a check reads call sites, imports, assignments and object-literal properties off the tokens, one statement deep, and follows nothing between statements or functions. The checks are exec.dynamic, exec.shell, deser.unsafe, net.egress, net.bind_all, tls.off, obfuscation, fs.outside, privacy.pii_log and dom.html_sink (Safe) and works.syntax, works.import_unresolved, works.relative_missing, works.entry_missing and works.tests_missing (Works). Not ported from the Python side: privacy.pii_prompt, works.test_no_assert, works.todo_stub, works.commented_code, works.dead_flag and the orphan (dead code) check; coverage.languages.javascript.not_checked lists them. Nothing is installed, imported or run: no npm, no node.

Generated files. A declaration file (*.d.ts), a minified or bundled file (*.min.js, *.min.mjs, *.bundle.js) and any JavaScript or TypeScript file with a line longer than 2,000 characters in its first 8 KB are counted as generated (files.generated). They get the secret scan and the obfuscation and exec.dynamic token checks only, an exec.dynamic WARN there is reported at INFO, and they get no Works check.

When there is neither Python nor JavaScript / TypeScript source, Works is not scored (n/a (no Python or JavaScript), null in JSON), Safe is labelled partial, Overall comes from the scored dimensions only, and the status is PARTIAL. A repo whose source is mostly in other languages is also PARTIAL with the same scores (rule in Scan status). PARTIAL means "do not read this grade as covering the whole repo"; it never fails --fail-on on its own. What the token level cannot see is in Limitations.

Install

pip install code-guardian-mcp

The distribution is code-guardian-mcp (code-guardian on PyPI is someone else's project); the commands are code-guardian and code-guardian-mcp. To run the MCP server without installing anything: uvx code-guardian-mcp mcp.

From a clone (for the tests):

git clone https://github.com/LuminariSoftwares/code-guardian.git

cd code-guardian python -m venv .venv .venv\Scripts\activate # Windows; macOS/Linux: source .venv/bin/activate pip install -e ".[test]" python -m pytest -q

The [test] extra is pytest, build and jsonschema — the whole suite needs them, and the package's own runtime dependencies stay empty. See CONTRIBUTING.md.

The app

code-guardian ui shows the same scan as a page in your browser, in plain words, for people who use AI to write code but do not read code well. code-guardian ui PATH checks that folder first; code-guardian ui alone opens the page and you pick a folder there. It prints one line, code-guardian ui: open http://127.0.0.1:8765/#t=…, and opens that link in your browser; the part after #t= is a key for this run, so use the printed link, not just the address. The page never changes your files, and the grade and findings are the ones code-guardian scan gives.

Settings

The gear at the top of every screen opens three choices: Theme (Dark, the default, or Light), Text size (Normal, Larger or Largest) and whether the Luminari name shows at the top. Your choices are kept by this browser only, not in a file on the computer and not by code-guardian, so another browser or a private window starts from the defaults. The page never turns light because your computer is set to light; light is only ever your choice.

Sizes

Every screen fits a phone, a narrow side window (about 520 px wide) and a full or wide screen, at all three text sizes, with nothing cut off: on a phone or in a side window the summary becomes one line under the tabs that you tap to open, and the file list on the Code screen becomes a drawer. The phone is shown below; the same screen at the other sizes is result_520x900.png (side window) and result_1280x800.png (full screen).

Every file

The Code screen lists every file the check saw, not only the files with a finding, and gives each file one word. A file with a safety finding is marked High, Medium or Low by its worst one. The filter above the list picks which files you see, each with its count:

• All files: every file the check saw.
• Files with findings: files with at least one finding of any kind.
• No known risks found: a Python fil