git-prism-0.9.1 is not a library.

git-prism

Agent-optimized git data for LLM agents. Five MCP tools that replace human-oriented diffs with structured JSON -- function-level granularity, import tracking, dependency changes, complete file snapshots, per-commit history, function context (callers, callees, test references), and a one-call review_change orchestration that combines manifest and function-context for PR review.

The Problem

Git's porcelain output (diff, log, --stat) is designed for human eyes. When an LLM agent parses a unified diff, it burns tokens on @@ hunk headers, +/- line prefixes, and whitespace context that carries no semantic meaning. Worse, it has to reconstruct what actually changed -- which functions were modified, which imports were added, whether the file is generated -- from raw text.

git-prism gives agents structured data directly: a change manifest with per-file metadata and function-level analysis, plus full before/after file content when deeper inspection is needed.

Installation

From crates.io (recommended)

cargo install git-prism

From source

cargo install --path .

Binary download

Grab a prebuilt binary from the GitHub Releases page.

Homebrew (macOS and Linux)

brew tap mikelane/tap
brew install git-prism

MCP Registration

claude mcp add git-prism -- git-prism serve

That's it. The server uses stdio transport and is available in all Claude Code sessions.

Redirect hook (removed in v0.9.0)

Earlier versions bundled a Claude Code PreToolUse redirect hook, installed via git-prism hooks install. It was removed in v0.9.0: the PATH shim below is a strict superset of its coverage and the hook's structural blind spots made it the weaker of the two. See ADR 0010 and ADR 0011 for the rationale.

git-prism hooks install now exits with an error directing you to git-prism shim install. If you ran the old redirect hook, clean up its leftover PreToolUse entry:

git-prism hooks uninstall   # removes the legacy git-prism-bash-redirect-v1 settings.json entry
git-prism hooks status      # reports whether a legacy entry remains, and at which scope

PATH shim

Install is Unix-only. git-prism shim install creates a symlink and relies on process-level interception; it cleanly bails on non-Unix platforms ("not supported on non-Unix platforms"). The passthrough code paths build and run on Windows (see #322), but the install flow itself assumes macOS or Linux.

What it does and why

A Claude Code PreToolUse hook only ever fires inside Claude Code's PreToolUse pipeline. Agents that shell out to git through other channels — a subprocess, a shell tool, a build script, a wrapper — never hit it. That blind spot is why the bundled redirect hook was removed in favor of the PATH shim, which closes the gap at the process level.

When installed, git-prism is placed on your PATH as a binary literally named git, ahead of the real git. Every git invocation flows through git-prism first. The shim then decides, per command:

AI agent + a watch-list subcommand with a ref range → route to git-prism's structured-JSON path (the same data the MCP tools return) instead of porcelain. The watch list is diff, log, show, blame, and pickaxe forms (-S/-G), but only when a ref range is present (e.g. git diff main..HEAD).
Everything else — humans, CI, non-agents, ref-range-less commands like git status or a bare git diff — falls straight through to the real git binary, unchanged.

Agent detection reuses the env-var-only logic behind git-prism agent-detect: no agent signal (or CI=true) means vanilla git, always. The classifier and watch list live in src/shim/classify.rs; the real-git resolver that walks PATH (skipping the shim's own directory) lives in src/shim/real_git.rs.

Install

git-prism shim install

This creates a symlink at ~/.local/share/git-prism/bin/git pointing at the git-prism binary and prints both the created path and the line to add to your shell profile:

Created symlink: /home/you/.local/share/git-prism/bin/git
Add this to your shell init (~/.zshrc or ~/.bashrc):
  export PATH="$HOME/.local/share/git-prism/bin:$PATH"

Add that export line to your shell profile so the shim directory precedes the real git on PATH, then open a new shell.

To check status or remove the shim:

git-prism shim status     # reports installed / not installed + directory
git-prism shim uninstall  # removes the symlink

Deprecated: git-prism hooks install --path-shim still works in this release but prints a deprecation warning. Use git-prism shim install instead.

Smoke test

# 1. Install and wire up PATH
git-prism shim install
export PATH="$HOME/.local/share/git-prism/bin:$PATH"

# 2. As a non-agent, you get vanilla git — passthrough
git --version            # prints the real git version

# 3. As an agent, a ref-range diff is intercepted and returns structured JSON
AI_AGENT=smoke-test git diff HEAD~1..HEAD | head -c 80
# => {"metadata":{ ... structured manifest ...

# 4. A ref-range-less command always passes through, even for an agent
AI_AGENT=smoke-test git status   # plain porcelain

Escape hatch and loop prevention

The shim sets GIT_PRISM_INSIDE_SHIM=1 in every child process it spawns. When the shim sees that variable already set, it forces passthrough — so nested git calls (a lefthook pre-push hook, cargo's internal git, a build script that shells out to git) never recurse back into the shim and loop. You can set it yourself to force vanilla git for one command:

GIT_PRISM_INSIDE_SHIM=1 git diff main..HEAD   # bypasses the shim

Debugging

Set GIT_PRISM_DEBUG_RESOLVER=1 to print the resolved real-git path to stderr, so you can confirm which git binary the shim is delegating to:

GIT_PRISM_DEBUG_RESOLVER=1 git status
# (stderr) git-prism shim: resolved real git to /usr/bin/git

Coexisting with rtk

If you use rtk (or any tool that also wraps git on PATH), the two wrappers will fight over the same command. Tell rtk to leave git alone by adding it to rtk's exclude list in ~/Library/Application Support/rtk/config.toml:

exclude_commands = ["git"]

Uninstall

git-prism hooks uninstall --path-shim   # removes the symlink
git-prism hooks status                  # reflects path-shim presence/absence

After uninstalling, remove the export PATH=... line you added to your shell profile.

A narrated end-to-end walkthrough of the shim lives at demo/path-shim.mp4.

Agent detection

git-prism agent-detect

Prints a JSON object indicating whether the current process is running on behalf of an AI coding agent, detected via environment variables only.

{ "agent": "ClaudeCode", "signal": "ToolSpecific" }

Both fields are null when no agent is detected, or when CI=true is set (CI wins over all agent signals).

Detection priority order:

AI_AGENT non-empty (Vercel cross-tool convention, e.g. claude-code_2-1-141_agent) → signal: "AiAgent"
AGENT set with an allowlisted value (goose, amp) → signal: "Agent". Bare AGENT=1 is intentionally ignored (collides with ssh-agent and build-system agents).
Tool-specific markers: CLAUDECODE, CURSOR_AGENT, GEMINI_CLI, CODEX_SANDBOX, CLINE_ACTIVE, AUGMENT_AGENT, OPENCODE_CLIENT, TRAE_AI_SHELL_ID → signal: "ToolSpecific"
CI set → {"agent": null, "signal": null} regardless of any agent markers above.

This subcommand is a diagnostics/ops tool. It is not exposed as an MCP tool — it does not appear in the MCP tool registry and existing tools are unaffected.

Tools

`get_change_manifest`

Returns structured metadata about what changed between two git refs.

Parameters:

Parameter	Type	Default	Description
`base_ref`	string	(required)	Base git ref (commit SHA, branch, tag, `HEAD~1`)
`head_ref`	string	(omitted → working tree)	Head git ref. When the field is omitted from the request, the tool compares `base_ref` against the working tree (staged + unstaged changes) instead of diffing two commits. Passing `"HEAD"` explicitly produces a committed-mode diff against `HEAD`, which is distinct from working-tree mode.
`repo_path`	string	cwd	Path to the git repository
`include_patterns`	string[]	`[]`	Glob patterns to include (e.g. `[".rs", ".go"]`)
`exclude_patterns`	string[]	`[]`	Glob patterns to exclude (e.g. `["*.lock"]`)
`include_function_analysis`	bool	`false`	Enable tree-sitter function/import analysis (opt-in; default keeps the response compact)
`cursor`	string	`null`	Opaque pagination cursor from a previous response
`page_size`	int	`100`	Max file entries per page (1-500)

Example output:

{
  "metadata": {
    "repo_path": "/home/user/myproject",
    "base_ref": "main",
    "head_ref": "HEAD",
    "base_sha": "a1b2c3d4e5f6",
    "head_sha": "f6e5d4c3b2a1",
    "generated_at": "2026-04-03T12:00:00Z",
    "version": "x.y.z"
  },
  "summary": {
    "total_files_changed": 3,
    "files_added": 1,
    "files_modified": 2,
    "files_deleted": 0,
    "files_renamed": 0,
    "total_lines_added": 47,
    "total_lines_removed": 12,
    "total_functions_changed": 4,
    "languages_affected": ["go", "rust"]
  },
  "files": [
    {
      "path": "src/handler.go",
      "old_path": null,
      "change_type": "modified",
      "change_scope": "committed",
      "language": "go",
      "is_binary": false,
      "is_generated": false,
      "lines_added": 25,
      "lines_removed": 8,
      "size_before": 1200,
      "size_after": 1450,
      "functions_changed": [
        {
          "name": "HandleRequest",
          "old_name": null,
          "change_type": "signature_changed",
          "start_line": 15,
          "end_line": 42,
          "signature": "func HandleRequest(ctx context.Context, req *Request) (*Response, error)"
        },
        {
          "name": "validateInput",
          "old_name": "checkInput",
          "change_type": "renamed",
          "start_line": 44,
          "end_line": 58,
          "signature": "func validateInput(req *Request) error"
        }
      ],
      "imports_changed": {
        "added": ["context", "errors"],
        "removed": ["log"]
      }
    }
  ],
  "dependency_changes": [
    {
      "file": "go.mod",
      "added": [{"name": "github.com/pkg/errors", "old_version": null, "new_version": "v0.9.1"}],
      "removed": [],
      "changed": []
    }
  ],
  "pagination": {
    "total_items": 3,
    "page_start": 0,
    "page_size": 100,
    "next_cursor": null
  }
}

`get_file_snapshots`

Returns complete before/after file content at two git refs. No diffs to parse -- the agent gets the full file at each point in time.

Parameters:

Parameter	Type	Default	Description
`base_ref`	string	(required)	Base git ref
`head_ref`	string	`"HEAD"`	Head git ref
`paths`	string[]	(required)	File paths to snapshot (max 20)
`repo_path`	string	cwd	Path to the git repository
`include_before`	bool	`true`	Include file content at base ref
`include_after`	bool	`true`	Include file content at head ref
`max_file_size_bytes`	int	`100000`	Truncate files larger than this
`line_range`	[int, int]	`null`	Return only lines in this range (1-indexed)
`include_diff_hunks`	bool	`false`	Include hunk boundaries for diff-relative line mapping

Example output:

{
  "metadata": {
    "repo_path": "/home/user/myproject",
    "base_ref": "main",
    "head_ref": "HEAD",
    "generated_at": "2026-04-03T12:00:00Z"
  },
  "files": [
    {
      "path": "src/handler.go",
      "language": "go",
      "is_binary": false,
      "before": {
        "content": "package main\n\nfunc HandleRequest(req *Request) error {\n    // old implementation\n}\n",
        "line_count": 5,
        "size_bytes": 82,
        "truncated": false
      },
      "after": {
        "content": "package main\n\nimport \"context\"\n\nfunc HandleRequest(ctx context.Context, req *Request) (*Response, error) {\n    // new implementation\n}\n",
        "line_count": 7,
        "size_bytes": 130,
        "truncated": false
      },
      "error": null
    }
  ],
  "token_estimate": 53
}

`get_commit_history`

Returns one manifest per commit in a range, so agents can see what changed in each commit separately instead of a single collapsed diff.

Parameters:

Parameter	Type	Default	Description
`base_ref`	string	(required)	Base git ref (exclusive -- commits after this)
`head_ref`	string	(required)	Head git ref (inclusive)
`repo_path`	string	cwd	Path to the git repository
`cursor`	string	`null`	Opaque pagination cursor from a previous response
`page_size`	int	`100`	Max commits per page (1-500)

Example output:

{
  "commits": [
    {
      "metadata": {
        "sha": "a1b2c3d4",
        "message": "add validation helper",
        "author": "Jane Dev",
        "timestamp": "2026-04-03T10:30:00+00:00"
      },
      "files": [
        {
          "path": "src/validate.rs",
          "change_type": "added",
          "language": "rust",
          "lines_added": 25,
          "lines_removed": 0
        }
      ],
      "summary": {
        "total_files_changed": 1,
        "files_added": 1,
        "total_lines_added": 25,
        "total_lines_removed": 0
      }
    }
  ],
  "pagination": {
    "total_items": 1,
    "page_start": 0,
    "page_size": 100,
    "next_cursor": null
  }
}

`get_function_context`

Returns callers, callees, and test references for each function that changed between two refs. Answers "what calls this function?" and "what does this function call?" without the agent having to grep.

Uses import-aware scoping for Rust, Python, Go, and TypeScript/JavaScript to filter the caller scan to files that actually import the changed module. This eliminates false positives from leaf-name collisions and improves performance on large repos. Unsupported languages fall back to full-repo scanning.

Parameters:

Parameter	Type	Default	Description
`base_ref`	string	(required)	Base git ref
`head_ref`	string	(required)	Head git ref
`repo_path`	string	cwd	Path to the git repository
`cursor`	string	`null`	Opaque pagination cursor from a previous response
`page_size`	int	`25`	Max function entries per page (1-500). Lower default than the manifest tool because each entry carries caller/callee lists
`function_names`	string[]	`null`	Restrict the response to functions with these names. Use this to re-query a function whose lists were clamped on a prior call
`max_response_tokens`	int	`8192`	Response-size budget in estimated tokens. When exceeded, caller/callee lists are trimmed per entry. `0` disables the budget

Example output:

{
  "metadata": {
    "base_ref": "HEAD~1",
    "head_ref": "HEAD",
    "base_sha": "a1b2c3d4",
    "head_sha": "f6e5d4c3",
    "generated_at": "2026-04-09T12:00:00Z"
  },
  "functions": [
    {
      "name": "validate_input",
      "file": "src/validation.rs",
      "change_type": "modified",
      "blast_radius": {
        "production_callers": 1,
        "test_callers": 1,
        "has_tests": true,
        "risk": "low"
      },
      "scoping_mode": "scoped",
      "callers": [
        { "file": "src/handler.rs", "line": 42, "caller": "handle_request", "is_test": false }
      ],
      "callees": [
        { "callee": "check_length", "line": 15 },
        { "callee": "check_format", "line": 18 }
      ],
      "test_references": [
        { "file": "tests/test_validation.rs", "line": 10, "caller": "test_validate_empty", "is_test": true }
      ],
      "caller_count": 2
    }
  ]
}

The scoping_mode field indicates how the caller scan was performed: "scoped" means import-based filtering was used (more precise but may miss callers that use unusual import patterns), while "fallback" means the scan parsed every file in the repo (authoritative but slower). Use this to decide whether a zero-caller result is definitive or potentially incomplete.

`review_change`

Returns combined change manifest and function-level blast radius for a ref range, in one call. Use this instead of git diff <ref>..<ref> when reviewing a PR, auditing a refactor, or assessing merge safety -- it answers "what changed and what might break" in one tool invocation, with structured JSON instead of raw diff text.

Replaces the common two-step workflow (get_change_manifest then get_function_context) with a single call that runs both internally and splits the response-size budget 40/60 (manifest / function_context).

Parameters:

Parameter	Type	Default	Description
`base_ref`	string	(required)	Base git ref
`head_ref`	string	(omitted → working tree)	Head git ref. Omit to compare against the working tree (manifest only; the function-context half returns empty since callers/callees need committed content)
`repo_path`	string	cwd	Path to the git repository
`include_patterns`	string[]	`[]`	Glob patterns to include
`exclude_patterns`	string[]	`[]`	Glob patterns to exclude
`function_names`	string[]	`null`	Restrict the function-context half to these names
`max_response_tokens`	int	`8192`	Combined budget; split 40/60 between manifest and function_context. `0` disables both halves' budgets
`manifest_cursor`	string	`null`	Opaque cursor advancing only the manifest half
`function_context_cursor`	string	`null`	Opaque cursor advancing only the function-context half
`page_size`	int	`25`	Page size used for both halves

The two cursors are independent so an agent can advance one half (e.g., walk through a long file list) without re-paginating the other. Each sub-response carries its share of the budget in metadata.budget_tokens so downstream observability can audit the split decision.

Example output:

{
  "manifest": {
    "metadata": {
      "base_ref": "HEAD~1",
      "head_ref": "HEAD",
      "budget_tokens": 1638,
      "...": "..."
    },
    "summary": { "total_files_changed": 3, "...": "..." },
    "files": [{ "path": "src/lib.rs", "...": "..." }],
    "pagination": { "next_cursor": null, "...": "..." }
  },
  "function_context": {
    "metadata": {
      "base_ref": "HEAD~1",
      "head_ref": "HEAD",
      "budget_tokens": 2458,
      "...": "..."
    },
    "functions": [{ "name": "validate", "blast_radius": { "risk": "medium" }, "...": "..." }],
    "pagination": { "next_cursor": null, "...": "..." }
  }
}

CLI Usage

git-prism also works as a standalone CLI for scripting and debugging:

# Change manifest between two refs
git-prism manifest HEAD~1..HEAD

# Manifest for a specific repo path
git-prism manifest main..feature-branch --repo /path/to/repo

# Per-commit history for a range
git-prism history HEAD~5..HEAD

# Smaller pages for constrained environments
git-prism manifest main..HEAD --page-size 50

# File snapshots for specific paths
git-prism snapshot HEAD~3..HEAD --paths src/main.rs src/lib.rs

# Function context (callers, callees, test references)
git-prism context HEAD~1..HEAD

# List supported languages
git-prism languages

The manifest, snapshot, history, and context commands output JSON to stdout. The manifest and history commands auto-paginate internally (default page size 500, configurable with --page-size) and always return the complete result. The languages command outputs plain text.

Agent Workflow

One-call path: PR review and refactor audits

For PR review, refactor audits, or any "what changed and what might break" question, use review_change instead of git diff:

review_change(base_ref="main", head_ref="HEAD")

This returns a combined { manifest, function_context } payload in one call, splitting the token budget 40/60 between the two halves. It replaces the two-step manifest + function_context workflow when you need both in the same session.

Three-call path: targeted inspection

When you need finer control -- different budgets per half, filtering by function name, or deep-diving into specific files -- use the individual tools in order:

Step 1: Triage with get_change_manifest

Ask for the manifest to understand the shape of a change. The summary tells you file counts, line counts, and affected languages. The per-file entries tell you which functions changed signatures, which imports were added, and whether files are generated (safe to skip).

Step 2: Blast radius with get_function_context

For the changed functions identified in step 1, request function context. This tells you which other files call each changed function, what each changed function calls, and which test files reference it. Each function includes a blast_radius object with a risk level (none, low, medium, high) computed from production caller count and test coverage -- sort by risk to review the highest-impact changes first. The agent never has to grep through the codebase to find callers or guess which tests to check.

Step 3: Deep dive with get_file_snapshots

Once you know which files and callers matter, request full snapshots of the highest-impact files. You get complete before/after content -- no reconstructing files from diff hunks. Use line_range to focus on specific sections and include_before: false when you only need the current state. Pass include_diff_hunks: true to get unified-diff hunk boundaries for computing diff-relative line positions (e.g., for GitHub inline review comments).

Both paths keep token usage low. review_change is the most efficient starting point for most review tasks; the three-call path is worth it when you need targeted re-queries or want to page through a large manifest separately from a large function list.

Pagination

get_change_manifest and get_commit_history return a pagination object on every response:

"pagination": {
  "total_items": 842,
  "page_start": 0,
  "page_size": 100,
  "next_cursor": "eyJvZmZzZXQiOjEwMCwiYmFzZV9zaGEiOiIuLi4ifQ=="
}

When next_cursor is non-null, pass it back as the cursor parameter on the next call to fetch the following page. The cursor is an opaque base64 payload that encodes the page offset plus the resolved base/head SHAs; the server rejects a cursor whose SHAs no longer match the refs supplied in the follow-up call, so a cursor minted against main..feature cannot be reused against a different range. The manifest summary always reflects all files in the changeset regardless of which page is returned, so agents can triage from page 1 before deciding whether to page through the remaining file entries.

page_size is clamped server-side to the 1..=500 range; values outside that range are coerced rather than rejected. The CLI (git-prism manifest, git-prism history) paginates internally and always returns the complete result; the cursor contract is only visible through the MCP tool interface.

Supported Languages

Function-level analysis uses tree-sitter to extract functions, methods, imports, and call sites from source code.

Language	Extensions	Extracts
C	`.c`, `.h`	functions, declarations, `#include` directives
C++	`.cpp`, `.hpp`, `.cc`, `.cxx`, `.hh`, `.hxx`	class/namespace-qualified methods, functions, `extern "C"` blocks, `#include` directives
C#	`.cs`	methods, constructors, `using` directives
Go	`.go`	functions, methods, imports
Java	`.java`	methods, constructors, imports
JavaScript	`.js`, `.jsx`	functions, exported functions, arrow functions, methods, imports
Kotlin	`.kt`, `.kts`	functions, methods, extension functions, imports
PHP	`.php`	functions, methods, `use` declarations
Python	`.py`	functions, decorated functions, methods, imports
Ruby	`.rb`	methods, singleton methods, `require`/`require_relative`
Rust	`.rs`	functions, methods, use statements
Swift	`.swift`	functions, methods, init declarations, imports
TypeScript	`.ts`, `.tsx`	functions, exported functions, arrow functions, methods, imports

Files in unsupported languages still appear in the manifest with full line/size/change-type metadata -- functions_changed is null (not an empty array) to distinguish "no grammar available" from "analyzed, nothing changed."

Content-Aware Function Diffing

Function changes are detected by comparing SHA-256 hashes of function body content, not line positions. This means:

Reordered functions (moved but not modified) produce no change entries, eliminating false positives that waste agent attention.
Body-only changes (same signature, different implementation) are detected as modified, even when line numbers don't shift.
Renamed functions are detected when an unmatched added function shares a body hash with an unmatched deleted function. These produce a single renamed entry with old_name populated, instead of separate deleted + added.

The change_type values for functions are: added, modified, deleted, signature_changed, renamed. Renamed entries carry the previous name in the old_name field (null for all other variants) so agents can correlate the post-rename function back to its history.

Whitespace and comment sensitivity. The body hash is computed over the raw byte span of the function body as tree-sitter sees it. Reformatting runs, comment additions or removals, trailing-whitespace changes, and indentation shifts will therefore change the hash and produce a modified entry even when the executable logic is unchanged. A future release may normalize whitespace and strip comments before hashing; until then, running a formatter on a file will show every touched function as modified on the next manifest call.

Dependency File Tracking

git-prism parses dependency files and reports added, removed, and version-changed packages:

Cargo.toml (Rust)
package.json (Node.js)
go.mod (Go)
pyproject.toml (Python, PEP 621)

Telemetry

Optional OpenTelemetry instrumentation, disabled by default and opt-in via environment variables.

Variable	Purpose	Default
`GIT_PRISM_OTLP_ENDPOINT`	OTLP gRPC endpoint URL. When unset, telemetry is disabled.	unset (disabled)
`GIT_PRISM_OTLP_HEADERS`	Planned, not yet wired (#43). Setting this variable has no effect today; managed OTLP backends that require auth headers need a local collector proxy.	unset
`GIT_PRISM_SERVICE_NAME`	Service name reported to the backend.	`git-prism`
`GIT_PRISM_SERVICE_VERSION`	Service version reported to the backend.	crate version

Quick start with Jaeger (any OTLP-compatible backend works):

docker run -d --name jaeger -p 4317:4317 -p 16686:16686 jaegertracing/all-in-one:latest
GIT_PRISM_OTLP_ENDPOINT=http://localhost:4317 git-prism serve

Privacy: No raw paths, file contents, author names, or ref names are exported. Paths are SHA-256 hashed; refs normalized to a bounded enum. See docs/telemetry.md.

Contributing

See CONTRIBUTING.md.

License

Apache-2.0

git-prism 0.9.1

git-prism

The Problem

Installation

From crates.io (recommended)

From source

Binary download

Homebrew (macOS and Linux)

MCP Registration

Redirect hook (removed in v0.9.0)

PATH shim

What it does and why

Install

Smoke test

Escape hatch and loop prevention

Debugging

Coexisting with rtk

Uninstall

Agent detection

Tools

get_change_manifest

get_file_snapshots

get_commit_history

get_function_context

review_change

CLI Usage

Agent Workflow

One-call path: PR review and refactor audits

Three-call path: targeted inspection

Pagination

Supported Languages

Content-Aware Function Diffing

Dependency File Tracking

Telemetry

Contributing

License

`get_change_manifest`

`get_file_snapshots`

`get_commit_history`

`get_function_context`

`review_change`