{"repo": "ataraxy-labs/inspect", "files": {"README.md": {"90a8a5dd3a15c39e59062e2518171615fecff5c3": {"t": 1785674407.3730597, "n": 14123, "h": "47472675e21572b6", "c": "> **Part of the [Ataraxy Labs](https://ataraxy-labs.com) stack** — agent-native infrastructure for software development. See also: [sem](https://ataraxy-labs.com/sem) (semantic version control) · [weave](https://ataraxy-labs.com/weave) (entity-level merge driver) · [opensessions](https://github.com/Ataraxy-Labs/opensessions) (tmux sidebar for coding agents).\n>\n> Read the manifesto: https://ataraxy-labs.com/#thesis · Essays: https://ataraxy-labs.com/blogs · LLMs: https://ataraxy-labs.com/llms.txt\n\n

\n \"inspect\"\n

\n\n

\n inspect\n

\n\n

\n Entity-level code review for Git.
\n Triage PRs by structural risk, not line count.\n

\n\ninspect is a code review tool that works at the entity level instead of files or lines. It parses your diff with tree-sitter, classifies each changed entity (text-only, syntax, functional), scores it by risk using the cross-file dependency graph, and groups independent changes so tangled commits can be reviewed as separate units.\n\nEvery code review tool today shows you files and lines. inspect shows you which functions matter. A renamed variable, a reformatted function, and a deleted public API method all look the same in a line diff. inspect scores the API deletion as critical (high blast radius, many dependents) and the rename as low risk. Review the critical stuff first, skip the noise.\n\nOn the Greptile benchmark (141 findings across 52 PRs), inspect achieved 95.0% recall vs Greptile's 91.5% and CodeRabbit's 56.0%. On the Martian benchmark (137 findings, 50 PRs), inspect scored 46.2% F1, beating Augment Code (45.8%) for #1 on their leaderboard.\n\nAgents and CI pipelines consume inspect through JSON output or the built-in MCP server (6 tools). Developers use the CLI to triage locally before pushing.\n\n## The Problem\n\n`git diff` tells you 12 files changed. But which changes actually matter? A renamed variable, a reformatted function, and a deleted public API method all look the same in a line-level diff. You have to read every line to figure out what needs careful review and what can be skipped.\n\nThis gets worse with AI-generated code. DORA 2025 found that AI adoption led to +154% PR size, +91% review time, and +9% more bugs shipped. Reviewers are drowning in noise.\n\ninspect gives you two ways to handle this: local triage that ranks changes by structural risk, and optional LLM-powered review that finds the actual bugs.\n\n## What inspect Does\n\nFor every changed entity, inspect computes:\n\n- **Classification**: What kind of change is this? Text-only (comments/whitespace), syntax (signature/type change), functional (logic change), or a combination. Based on [ConGra](https://arxiv.org/abs/2409.14121).\n- **Risk score**: 0.0 to 1.0, combining classification, blast radius, dependent count, public API exposure, and change type. Cosmetic-only changes get a 70% discount.\n- **Blast radius**: How many entities are transitively affected if this change breaks something. Computed from the full repo entity graph, not just changed files.\n- **Grouping**: Union-Find untangling separates independent logical changes within a single commit, so tangled commits can be reviewed as separate units.\n\n```\n$ inspect diff HEAD~1\n\ninspect 12 entities changed\n 1 critical, 4 high, 6 medium, 1 low\n\ngroups 3 logical groups:\n [0] src/merge/ (5 entities)\n [1] src/driver/ (4 entities)\n [2] validate (3 entities)\n\nentities (by risk):\n\n ~ CRITICAL function merge_entities (src/merge/core.rs)\n classification: functional score: 0.82 blast: 171 deps: 3/12\n public API\n >>> 12 dependents may be affected\n\n - HIGH function old_validate (src/validate.rs)\n classification: functional score: 0.65 blast: 8 deps: 0/3\n public API\n\n + MEDIUM function parse_config (src/config.rs)\n classification: functional score: 0.45 blast: 0 deps: 2/0\n\n ~ LOW function format_output (src/display.rs)\n classification: text score: 0.05 blast: 0 deps: 0/0\n cosmetic only (no structural change)\n```\n\n## Two ways to use inspect\n\n**Local (free, open source):** CLI + MCP server. Entity triage, risk scoring, blast radius, commit untangling. `inspect review` sends the riskiest entities to any LLM you choose (Anthropic, OpenAI, Ollama, or any OpenAI-compatible server). No vendor lock-in.\n\n**Hosted API (optional):** Full review via `inspect.ataraxy-labs.com`. Goes further than local review with 9 specialized lenses, cross-model ensemble, and validation passes. Submit a PR, get back findings.\n\n## Install\n\n```bash\ncargo install --git https://github.com/Ataraxy-Labs/inspect inspect-cli\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/Ataraxy-Labs/inspect\ncd inspect && cargo build --release\n```\n\n## Commands\n\n### `inspect diff `\n\nReview entity-level changes for a commit or range.\n\n```bash\ninspect diff HEAD~1 # last commit\ninspect diff main..feature # branch comparison\ninspect diff abc123 # specific commit\ninspect diff HEAD~1 --context # show dependency details\ninspect diff HEAD~1 --min-risk high # only high/critical\ninspect diff HEAD~1 --format json # JSON output\ninspect diff HEAD~1 --format markdown # markdown output (for agents)\n```\n\n### `inspect pr `\n\nReview all changes in a GitHub pull request. Uses `gh` CLI to resolve base/head refs.\n\n```bash\ninspect pr 42\ninspect pr 42 --min-risk medium\ninspect pr 42 --format json\n```\n\n### `inspect file `\n\nReview uncommitted changes in a file.\n\n```bash\ninspect file src/main.rs\ninspect file src/main.rs --context\n```\n\n### `inspect review `\n\nTriage + LLM review. Triages entities by risk, sends the highest-risk ones to an LLM for review.\n\n```bash\ninspect review HEAD~1 # Anthropic (default)\ninspect review HEAD~1 --provider ollama --model llama3 # local Ollama\ninspect review HEAD~1 --api-base http://localhost:8000/v1 --model my-model # any OpenAI-compatible server\ninspect review HEAD~1 --min-risk medium # review more entities\ninspect review HEAD~1 --max-entities 20 # send more to LLM\n```\n\n### `inspect bench --repo `\n\nBenchmark entity-level review across a repo's commit history. Outputs JSON with per-commit details and aggregate metrics.\n\n```bash\ninspect bench --repo ~/my-project --limit 50\n```\n\n## LLM Providers\n\n`inspect review` works with Anthropic, OpenAI, and any OpenAI-compatible server (Ollama, vLLM, LM Studio, llama.cpp). Pass `--api-base` and it auto-detects the right client.\n\n```bash\n# Anthropic (default)\nexport ANTHROPIC_API_KEY=sk-ant-...\ninspect review HEAD~1\n\n# OpenAI\nexport OPENAI_API_KEY=sk-...\ninspect review HEAD~1 --provider openai --model gpt-4o\n\n# Ollama (local, no API key)\ninspect review HEAD~1 --provider ollama --model llama3\n\n# Any OpenAI-compatible endpoint (vLLM, LM Studio, etc.)\ninspect review HEAD~1 --api-base http://localhost:8000/v1 --model my-model\n```\n\n| Provider | API key env var | Default base URL |\n|----------|----------------|-----------------|\n| `anthropic` | ANTHROPIC_API_KEY | api.anthropic.com |\n| `openai` | OPENAI_API_KEY | api.openai.com/v1 |\n| `ollama` | none | localhost:11434/v1 |\n\n`--api-base` implies the OpenAI-compatible client, so you don't need `--provider` with it. `--provider ollama` implies `localhost:11434`, so you don't need `--api-base` with it.\n\n## MCP Server\n\ninspect ships an MCP server so any coding agent (Claude Code, Cursor, etc.) can use entity-level review as a tool.\n\n```bash\n# Build the MCP server\ncargo build -p inspect-mcp\n\n# Binary at target/debug/inspect-mcp\n```\n\n**6 tools:**\n\n| Tool | Purpose |\n|------|---------|\n| `inspect_triage` | Primary entry point. Full analysis sorted by risk with verdict. |\n| `inspect_entity` | Drill into one entity: before/after content, dependents, dependencies. |\n| `inspect_group` | Get all entities in a logical change group. |\n| `inspect_file` | Scope review to a single file. |\n| `inspect_stats` | Lightweight summary: stats, verdict, timing. No entity details. |\n| `inspect_risk_map` | File-level risk heatmap with per-file aggregate scores. |\n\n**Review verdict** (returned by triage and stats):\n- `likely_approvable`: All changes are cosmetic\n- `standard_review`: Normal changes, no high-risk entities\n- `requires_review`: High-risk entities present\n- `requires_careful_review`: Critical-risk entities present\n\nAdd to your Claude Code config:\n```json\n{\n \"mcpServers\": {\n \"inspect\": {\n \"command\": \"/path/to/inspect-mcp\"\n }\n }\n}\n```\n\n## Code Review Benchmark\n\ninspect + LLM vs Greptile vs CodeRabbit on the same dataset, same judge, same methodology. 141 planted bugs across 52 PRs in 5 production repos (Sentry, Cal.com, Grafana, Keycloak, Discourse).\n\n| Metric | inspect + LLM | Greptile API | CodeRabbit CLI |\n|--------|--------------|-------------|----------------|\n| Recall | **95.0%** | 91.5% | 56.0% |\n| Precision | 33.3% | 21.9% | **48.2%** |\n| F1 Score | 49.4% | 35.3% | **51.8%** |\n| HC Recall | **100%** | 94.1% | 60.8% |\n| Findings | 402 | 590 | 164 |\n\ninspect catches **95% of all bugs** and **100% of high-severity bugs**. CodeRabbit misses 44% of bugs overall and 39% of high-severity ones. Greptile has decent recall but produces 3x more noise.\n\nThe approach: entity-level triage cuts 100+ changed entities to the 60 riskiest, then sends each to an LLM for review. This costs a fraction of reviewing the full diff, with higher recall than tools that scan everything.\n\nDataset: [HuggingFace](https://huggingface.co/datasets/rs545837/inspect-greptile-bench). Judge: heuristic keyword matching applied identically to all tools.\n\n## Hosted API\n\nFor teams that don't want to manage LLM infrastructure, we run a hosted review service at `inspect.ataraxy-labs.com`. It goes beyond what `inspect review` does locally.\n\n**What the hosted API does differently:**\n\n1. Entity triage ranks changes by graph signals (same as local)\n2. 9 parallel review lenses: 6 specialized (data correctness, concurrency, contracts, security, typos, runtime) + 3 general\n3. Cross-model ensemble for higher recall\n4. Structural filter drops findings that reference files not in the diff\n5. Validation pass confirms each finding against the actual code\n\n```bash\n# Submit a PR for review\ncurl -X POST https://inspect.ataraxy-labs.com/api/review \\\n -H \"Authorization: Bearer insp_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"repo\":\"owner/repo\",\"pr_number\":123}'\n\n# Entity triage only (no LLM, returns in 1-3s)\ncurl -X POST https://inspect.ataraxy-labs.com/api/triage \\\n -H \"Authorization: Bearer insp_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"repo\":\"owner/repo\",\"pr_number\":123}'\n```\n\nGet an API key at [inspect.ataraxy-labs.com/dashboard/keys](https://inspect.ataraxy-labs.com/dashboard/keys).\n\n## Triage Benchmark\n\nResults from running `inspect bench` against three Rust codebases (89 commits, 8,870 entities total):\n\n| Metric | sem | weave | agenthub |\n|--------|-----|-------|----------|\n| Commits analyzed | 31 | 39 | 19 |\n| Entities reviewed | 4,955 | 2,803 | 1,112 |\n| Avg entities/commit | 159.8 | 71.9 | 58.5 |\n| Avg blast radius | 0.0 | 3.4 | 42.5 |\n| Max blast radius | 0 | 171 | **595** |\n| High/Critical ratio | 15.1% | 40.6% | **77.1%** |\n| Cross-file impact | 0% | 10.6% | **70.7%** |\n| Tangled commits | 96.8% | 69.2% | 94.7% |\n\nKey takeaways:\n\n- **Blast radius 595** means one entity change in agenthub could affect 595 other entities transitively. A line-level diff won't tell you this.\n- **70.7% cross-file impact** means most changes in agenthub ripple across file boundaries. Reviewing one file in isolation misses the picture.\n- **96.8% tangled commits** means almost every commit in sem contains multiple independent logical changes that should be reviewed separately.\n\n## Change Classification\n\nBased on [ConGra (arXiv:2409.14121)](https://arxiv.org/abs/2409.14121). Every change is classified along three dimensions, producing 7 categories:\n\n| Classification | What changed |\n|---------------|-------------|\n| Text | Comments, whitespace, docs only |\n| Syntax | Signatures, types, declarations (no logic) |\n| Functional | Logic or behavior |\n| Text+Syntax | Comments and signatures |\n| Text+Functional | Comments and logic |\n| Syntax+Functional | Signatures and logic |\n| Text+Syntax+Functional | All three dimensions |\n\n## Risk Scoring\n\nEach entity gets a risk score from 0.0 to 1.0:\n\n```\nscore = classification_weight (0.05 to 0.55)\n + blast_ratio * 0.3 (normalized by total entities)\n + ln(1 + dependents) * 0.1 (logarithmic)\n + public_api_boost (0.15 if public)\n + change_type_weight (0.05 to 0.2)\n\nif cosmetic_only: score *= 0.3\n```\n\nRisk levels: **Critical** (>= 0.7), **High** (>= 0.5), **Medium** (>= 0.3), **Low** (< 0.3)\n\n## Languages\n\nTypeScript, TSX, JavaScript, Python, Go, Rust, Java, C, C++, Ruby, C#, PHP, Swift, Kotlin, Elixir, Bash, HCL/Terraform, Fortran, Vue\n\nPowered by tree-sitter parsers from [sem-core](https://github.com/Ataraxy-Labs/sem).\n\n## Architecture\n\nThree crates:\n\n- **inspect-core**: Analysis engine. Entity extraction (via sem-core), change classification, risk scoring, Union-Find untangling, review verdict.\n- **inspect-cli**: CLI interface with terminal, JSON, and markdown formatters.\n- **inspect-mcp**: MCP server exposing 6 tools for agent integration.\n\n```\nGit diff\n -> sem-core: extract entities, compute semantic diff\n -> classify: ConGra taxonomy (text/syntax/functional)\n -> risk: score from classification + blast radius + dependents + public API\n -> untangle: Union-Find grouping on dependency edges\n -> verdict: LikelyApprovable / StandardReview / RequiresReview / RequiresCarefulReview\n -> format: terminal, JSON, or markdown output\n```\n\n## Part of the Ataraxy Labs stack\n\n- [**sem**](https://github.com/Ataraxy-Labs/sem): Entity-level diff, blame, graph, and impact analysis\n- [**weave**](https://github.com/Ataraxy-Labs/weave): Entity-level semantic merge driver for Git\n- [**inspect**](https://github.com/Ataraxy-Labs/inspect): Entity-level code review (this repo)\n"}}}}