codeprobe

One command. 21 scanners. SARIF + verdict + MCP.

codeprobe

codeprobe is the deterministic analysis layer for AI-assisted development. Run 21 scanners and merge to SARIF. Compute a 5-tier change verdict for CI gating. Expose the same pipeline to Claude Code, Claude Desktop, or any MCP client. Zero runtime LLM calls in the core.

Note

Disclaimer: The author is an AWS employee. This is not an official AWS project or service. It is not maintained, supported, or endorsed by AWS. The CLI and source code are provided AS IS without warranty of any kind.

Why codeprobe?

CI needs one answer per PR: merge, review, or block. Human reviewers need signal, not noise. AI coding assistants need deterministic context they can trust between turns.

codeprobe answers all three by chaining three deterministic layers: scanner results, temporal git signals, and a verdict engine that grades the change. Every layer is reproducible on the same commit. No layer calls an LLM.

Install once, bootstrap a repo, and the same pipeline powers your local mise check, your CI gate, and your editor agent.

Getting Started

Install

uv tool install codeprobe

Full setup (recommended)

One command wires up scanner config, git hooks, CI/CD, the Claude Code plugin, and the code intelligence graph:

codeprobe bootstrap .

This generates:

.codeprobe.toml — scanner configuration tuned to your stack
lefthook.yml — pre-commit and pre-push hooks
.github/workflows/codeprobe-analysis.yml — CI/CD with the verdict job wired
.claude/plugins/codeprobe/ — 6 skills + 9 agents + PostToolUse GitNexus reindex hook
.gitnexus/ — structural graph for impact analysis
CLAUDE.md — AI assistant instructions for your project

Scan, verdict, serve

codeprobe scan .                        # 21 scanners → .codeprobe/scan.sarif
codeprobe index .                       # temporal signals + structural graph
codeprobe verdict . --base origin/main  # 5-tier change verdict
codeprobe mcp serve                     # expose tools to an MCP client

What codeprobe does

Three layers, one pipeline.

1. Quality — 21 scanners, merged SARIF

Lint, typecheck, SAST, secrets, dependency audit, dead code, complexity, IaC, API contracts, container compose — all written to a single SARIF v2.1.0 file. Tools with native SARIF emit it directly. Others are converted.

2. Structure — GitNexus graph + 12 temporal git signals

codeprobe index runs GitNexus for the structural knowledge graph and writes .codeprobe/git_temporal.json with 12 deterministic per-file signals (fix-follow-feat density, bus factor via Gini, decayed churn, test ratio, revert count, co-authors, rename history, commit interval gaps, author departure, risk keywords, conventional-commit classification, branch divergence).

3. Decision — `codeprobe verdict`

The verdict engine takes a diff, maps changed files to symbols and communities, pulls blast radius from GitNexus impact, cross-references risk profiles and temporal trends, and emits a 5-tier verdict with a confidence score, reviewer recommendations, GitHub labels, a markdown PR comment, and a tier-mapped exit code.

All three layers are accessible from the CLI, mise tasks, a FastMCP server, and the Claude Code plugin.

                        codeprobe pipeline
  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐
  │   scanners   │    │   temporal   │    │     verdict      │
  │  (21 tools)  │───▶│ (git signals)│───▶│  (5-tier gate)   │
  └──────────────┘    └──────────────┘    └──────────────────┘
        │                   │                      │
        ▼                   ▼                      ▼
   scan.sarif      git_temporal.json      VerdictResponse
   (+ codeprobe    (12 signals/file)      (+ markdown + labels
     properties)                            + exit code)

Commands

Command	What it does
`codeprobe scan .`	Run all applicable scanners, produce merged SARIF with codeprobe properties
`codeprobe scan . --scanners ruff --scanners ty`	Run a subset (repeated flag, not comma-separated)
`codeprobe scan . --format sarif`	Raw SARIF JSON to stdout
`codeprobe index .`	Build the deterministic index (graph + temporal signals + heuristic summary)
`codeprobe verdict . --base origin/main`	Compute the change verdict
`codeprobe verdict . --output-format markdown`	Emit a PR-ready markdown comment
`codeprobe verdict . --exit-code`	Exit 0/1/2/3 per tier for CI gating
`codeprobe mcp serve`	Stdio MCP server exposing 7 read-only tools
`codeprobe mcp serve --http 4748`	HTTP MCP server on 127.0.0.1:4748
`codeprobe detect .`	Auto-detect languages, frameworks, IaC, API contracts
`codeprobe init .`	Generate `.codeprobe.toml` only
`codeprobe ci-init .`	Generate GitHub Actions / GitLab CI workflow files
`codeprobe bootstrap .`	Run all setup stages (config + hooks + CI + plugin + gitnexus + claude-md)
`codeprobe check`	Verify external tool availability

See the CLI reference for every flag and exit code.

Scanners

21 scanners. Selection is driven by detect_project() against the ScannerSpec catalog in src/codeprobe/scanners/catalog.py.

Scanner	Category	Scope	SARIF native
ruff	lint	Python	Yes
ty	typecheck	Python	--
bandit	sast	Python	Yes
vulture	dead-code	Python	--
radon	complexity	Python	--
pip_audit	deps	Python	--
biome	lint	TypeScript / JS	--
tsc	typecheck	TypeScript	--
npm_audit	deps	TypeScript / JS	--
semgrep	sast	All languages	Yes
betterleaks	secrets	All languages	Yes
osv	deps	All languages	Yes
grype	deps	All languages	Yes
clamav	sast	All files	--
gitnexus	graph	All languages	--
checkov	sast	Terraform, CFN, Docker, K8s	Yes
docker_compose	sast	docker-compose (Checkov `yaml,secrets` frameworks)	Yes
tflint	lint	Terraform	Yes
hadolint	lint	Dockerfiles	Yes
trivy	sast	Terraform, Docker, K8s	Yes
openapi	api	OpenAPI 3.x, Swagger 2.0 (Spectral)	Yes

The openapi scanner wraps Spectral 6.15.0 with native --format sarif. The docker_compose scanner wraps Checkov with --framework yaml,secrets and emits checkov-docker-compose as a distinct Run so it does not collide with the general IaC Checkov scanner. See docs/user-guide/scanners/.

Bootstrap

codeprobe bootstrap . runs six stages. Each stage is independent — use --only config,hooks or --skip gitnexus to run subsets. Existing files are skipped unless --force.

Stage	Artifact	Behavior
`config`	`.codeprobe.toml`	Detects profile, writes scanner selection
`hooks`	`lefthook.yml`	Composes pre-commit / pre-push from `ScannerSpec`
`ci`	`.github/workflows/codeprobe-analysis.yml`, `.codeprobe-ci.yml`	Wires nightly + on-merge + PR-verdict cadences
`plugin`	`.claude/plugins/codeprobe/`	Skills, agents, PostToolUse GitNexus hook, MCP server registration
`gitnexus`	`.gitnexus/`	Builds the structural knowledge graph (Docker sidecar or `npx`)
`claude-md`	`CLAUDE.md`	Renders project-scoped AI assistant instructions

GitNexus is pinned to 1.6.2 via mise.toml. The bootstrap prefers a Docker sidecar built from src/codeprobe/ci/templates/gitnexus-sidecar.Dockerfile (the published GitNexus image is a web-UI server, not the CLI — so codeprobe builds its own). If Docker is absent, it falls back to npx gitnexus@1.6.2.

The PostToolUse hook at .claude/plugins/codeprobe/hooks/post-tool-use-gitnexus.sh auto-reindexes after git commit and git merge inside Claude Code sessions, so the graph stays current without user action.

Claude Code plugin

The bundled plugin (v1.1.1) ships 6 skills, 9 agents, one PostToolUse hook, and the MCP server.

Skills

Skill	Purpose
`/probe`	Run scanners and interpret findings in one shot
`/configure`	Auto-detect, recommend scanners, generate `.codeprobe.toml`
`/interpret`	Read existing SARIF and explain findings in context
`/document`	Dispatch the 8 documentation agents, produce 35+ cross-linked markdown files
`/bootstrap`	Run the full bootstrap pipeline from Claude Code
`/trust-model`	Review the deterministic-analysis trust boundary and data flow

MCP server

Register codeprobe mcp serve as a Claude Code MCP server:

{
  "mcpServers": {
    "codeprobe": {
      "command": "codeprobe",
      "args": ["mcp", "serve"]
    }
  }
}

The server exposes 7 read-only tools: scan, verdict, detect, check, temporal_signals, list_scanners, index_status. All tools return JSON-serializable dicts and handle invalid paths with {"error": ...} rather than raising. See docs/mcp.md and the MCP server guide.

SARIF extensions

codeprobe attaches a properties bag to every Result and Run in the merged SARIF, namespaced under codeprobe.*.

Per-result keys: codeprobe.blast_radius, codeprobe.churn_rank, codeprobe.temporal_fix_density, codeprobe.test_ratio, codeprobe.decayed_churn, codeprobe.bus_factor.

Per-run keys: codeprobe.enriched_at, codeprobe.enrichment_version, codeprobe.sources.

Writes go to properties, not fingerprints, so GitHub Advanced Security deduplication is unaffected. See docs/sarif-extensions.md for the schema and missing-data policy.

Temporal signals

codeprobe index writes .codeprobe/git_temporal.json with 12 deterministic per-file signals. All are subprocess-only — git log, git for-each-ref, git rev-list --left-right — no LLM, no gh CLI.

Signal	Source
Conventional-commit classification	`CC_RE` regex on commit subjects
Fix-follow-feat density (48h)	Nagappan/Ball defect-proneness heuristic
Revert detection	`Revert "subject"` and `This reverts commit <sha>`
Bus factor	Gini coefficient of author commit distribution (numpy)
Co-author count	`Co-authored-by:` trailer
Decayed churn	Σ exp(-age_days / half_life_days), half-life default 90d
Risk keyword hits	`hotfix\|urgent\|rollback\|broken\|oops\|fixup\|WIP\|emergency`
Test ratio	Language-keyed test-file pairing
Rename history	`git log --follow --name-status`
Commit interval gaps	max / avg days between commits
Author departure	top contributor's last-seen age
Branch divergence	`git for-each-ref` + `git rev-list --left-right`

Performance: 520 files and 306 commits complete in roughly 20 seconds on this repo. Co-change stays under 100ms per file on the same corpus. See docs/user-guide/temporal-signals/.

Verdict engine

codeprobe verdict emits a 5-tier verdict with a tier-mapped exit code.

Tier	Exit	When
`auto_merge`	0	No escalation signals, fresh index, low blast radius
`single_review`	1	Warnings or stale index
`dual_review`	1	Multiple warnings or cross-community change
`expert_review`	2	Escalation signals, blast radius > 20, high-risk area
`block`	3	Blocking signals (critical security, blast radius > 50)

Drivers: blast-radius thresholds (5 / 20 / 50), cross-community count (3+ = escalation), affected-area risk recommendation, temporal risk trend (accelerating / degrading), security findings (critical → block), churn hotspots, bus-factor risk, index freshness (48h stale / 168h outdated).

Outputs: --output-format summary|json|markdown. The markdown output is a GitHub-ready PR comment with signals, reasoning, recommended reviewers, and borderline rationale. The snapshot sidechannel (--snapshot on by default) persists a RiskSnapshot to .codeprobe/history/ so trend analysis improves over time.

See docs/user-guide/verdict/.

Architecture

flowchart LR
  subgraph Scan
    A[21 scanners]
    B[merge_sarif]
    A --> B
  end
  subgraph Signals
    C[git history]
    D[temporal.py + indexer.py]
    C --> D
  end
  subgraph Decide
    E[verdict.compute_verdict]
    F[temporal.persist_risk_snapshot]
    E --> F
  end
  B --> G[.codeprobe/scan.sarif]
  D --> H[.codeprobe/git_temporal.json]
  G --> I[SARIF enrichment]
  H --> I
  I --> E
  E --> J[VerdictResponse]

Key source locations:

Path	Purpose
`src/codeprobe/cli.py`	CLI entry point (cyclopts)
`src/codeprobe/scanners/catalog.py`	`ScannerSpec` catalog with language / IaC / contract affinity
`src/codeprobe/scanners/runner.py`	Orchestrator — imports modules, collects SARIF
`src/codeprobe/scanners/enrichment.py`	SARIF `properties` bag injection
`src/codeprobe/sarif.py`	SARIF v2.1.0 Pydantic models + merge
`src/codeprobe/indexer.py`	Deterministic index pipeline (16 steps)
`src/codeprobe/tools/git.py`	12 temporal signal implementations
`src/codeprobe/verdict.py`	Verdict engine, tier computation, labels
`src/codeprobe/temporal.py`	Risk snapshots + trend computation
`src/codeprobe/mcp/server.py`	FastMCP server exposing 7 tools
`src/codeprobe/bootstrap/`	6-stage bootstrap pipeline
`src/codeprobe/ci/templates/`	GitHub Actions + GitLab CI + GitNexus sidecar Dockerfile

Output files

All codeprobe artifacts land in .codeprobe/:

File	Written by	Description
`scan.sarif`	`scan`	Merged SARIF with codeprobe properties bag
`git_temporal.json`	`index`	12 temporal signals per tracked file
`heuristic_summary.json`	`index`	Volume / health / git / graph / temporal rollup
`git_hotspots.json`	`index`	Top-30 churn files with percentages
`git_cochanges.json`	`index`	Co-change map for top hotspots
`CONTEXT.orientation.md`	`index`	Repomix token-aware orientation
`CONTEXT.signatures.md`	`index`	Repomix tree-sitter compressed signatures
`files.all.txt`	`index`	Complete file manifest
`history/risk_*.json`	`verdict`	Point-in-time risk snapshots (for trend analysis)

Development

Prerequisites

Python 3.13+ (managed via mise)
Node.js 22+ (managed via mise)
uv for Python package management
External CLIs (checked via codeprobe check): rg, gitnexus, repomix, semgrep, bandit, osv-scanner, betterleaks, trivy, grype, syft, checkov, tflint, hadolint, npx @stoplight/spectral-cli

Setup

git clone https://github.com/theagenticguy/codeprobe.git
cd codeprobe
mise install
uv sync --all-groups

Common tasks

Task	Command
Run CLI	`uv run codeprobe`
Run all scanners	`mise run scan`
Quick scan (ruff + ty + betterleaks)	`mise run scan:quick`
Lint	`mise run lint`
Format	`mise run format`
Type check	`mise run typecheck`
Test	`mise run test`
Skill-definition validation	`mise run test:skills`
Plugin version alignment	`mise run plugin:version-check`
Bootstrap drift check	`mise run bootstrap:verify`
All checks (default gate)	`mise run check`
Build	`mise run build`
Commit (conventional)	`uv run cz commit`
Bump version	`mise run bump`

The check aggregate depends on lint, format:check, typecheck, test, plugin:check, plugin:version-check, and bootstrap:verify. The last three catch plugin manifest drift, template drift, and marketplace-version skew before they escape to a release.

Git hooks (lefthook)

pre-commit: ruff check+fix, ruff format, ty check, betterleaks
commit-msg: conventional commit validation (commitizen)
pre-push: lint, format-check, typecheck, test, betterleaks, semgrep OWASP

Code style

Line length: 120
Python 3.13+ typing: list[str] not List[str], X | None not Optional[X]
Google-style docstrings
pathlib.Path over os.path
from __future__ import annotations in every module

Contributing

Contributions welcome. Open an issue or pull request.

All commits must follow Conventional Commits
Pre-commit hooks enforce lint, format, typecheck, and secret scanning
Pre-push hooks run the full test suite

Related projects

GitNexus — Tree-sitter structural knowledge graph + MCP tools (pinned to v1.6.2)
repomix — Code bundling with Tree-sitter compression
FastMCP — MCP server framework (pinned to 3.2.4)
ty — Python type checker from Astral
ruff — Python linter and formatter from Astral
Spectral — OpenAPI / AsyncAPI linter (pinned to 6.15.0)
SARIF v2.1.0 — OASIS standard output format
Model Context Protocol — Spec for MCP clients and servers

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.claude		.claude
.erpaval/archive		.erpaval/archive
.github		.github
assets		assets
docs		docs
openspec		openspec
scripts		scripts
src/codeprobe		src/codeprobe
tests		tests
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.python-version		.python-version
.semgrepignore		.semgrepignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SECURITY_INSIGHTS.yml		SECURITY_INSIGHTS.yml
lefthook.yml		lefthook.yml
mise.toml		mise.toml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository files navigation

codeprobe

Why codeprobe?

Getting Started

Install

Full setup (recommended)

Scan, verdict, serve

What codeprobe does

1. Quality — 21 scanners, merged SARIF

2. Structure — GitNexus graph + 12 temporal git signals

3. Decision — `codeprobe verdict`

Commands

Scanners

Bootstrap

Claude Code plugin

Skills

MCP server

SARIF extensions

Temporal signals

Verdict engine

Architecture

Output files

Development

Prerequisites

Setup

Common tasks

Git hooks (lefthook)

Code style

Contributing

Related projects

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

codeprobe

Why codeprobe?

Getting Started

Install

Full setup (recommended)

Scan, verdict, serve

What codeprobe does

1. Quality — 21 scanners, merged SARIF

2. Structure — GitNexus graph + 12 temporal git signals

3. Decision — codeprobe verdict

Commands

Scanners

Bootstrap

Claude Code plugin

Skills

MCP server

SARIF extensions

Temporal signals

Verdict engine

Architecture

Output files

Development

Prerequisites

Setup

Common tasks

Git hooks (lefthook)

Code style

Contributing

Related projects

License

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

3. Decision — `codeprobe verdict`