Gitinspect

A CLI tool (and optional HTTP/MCP server) that turns any Git repository — local path or remote URL — into a structured, token-efficient snapshot optimized for LLMs and AI agents. Works with any Git host using shallow clones.

Badges

Features

Token Budget Management

Estimate tokens as len(content)/4. Sort files by priority. Stop when the budget is exceeded. Never waste context window space on irrelevant files.

AI Agent Ready (MCP)

Built-in MCP server over stdio. Works with Claude, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible agent. Two tools: inspect_repo for full snapshots, list_repo_files for lightweight file listings.

Any Git Host

GitHub, GitLab, Bitbucket, self-hosted — works with any Git repository. Remote repos use shallow clone (--depth 1) and are cached by commit hash.

Smart File Priority

Files are sorted by importance: README first, then entry points (main.*), then manifests (go.mod, package.json, etc.), then build files (Makefile, Dockerfile), then everything else.

Dependency Extraction

Automatically parse go.mod, package.json, Cargo.toml, requirements.txt, and Gemfile for dependency awareness.

Binary File Detection

Automatically skips binary files (images, executables, archives, fonts, etc.) and non-UTF-8 content. No garbled output.

Comment Stripping

Remove single-line comments and blank lines based on file extension. Supports // (Go, C, JS, Java, Rust, etc.), # (Python, Shell, YAML, Ruby, etc.), -- (SQL, Lua, Haskell), and ; (Assembly).

Multiple Output Formats

JSON (default), plain text, or YAML. Perfect for piping into LLMs, saving to files, or programmatic consumption.

Installation

Quick Install (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/richie-rich90454/gitinspect/main/install.sh | bash

Or with wget:

wget -qO- https://raw.githubusercontent.com/richie-rich90454/gitinspect/main/install.sh | bash

💡 Set INSTALL_DIR to change the install location (default: /usr/local/bin):

curl -fsSL ... | INSTALL_DIR=~/.local/bin bash

Homebrew (macOS / Linux)

brew tap richie-rich90454/tap
brew install gitinspect

Scoop (Windows)

scoop bucket add gitinspect https://github.com/richie-rich90454/scoop-bucket
scoop install gitinspect

Go Install

go install github.com/richie-rich90454/gitinspect/cmd/gitinspect@latest

Binary Download

Download the latest binary for your platform from the Releases page.

Debian / RPM / APK

sudo dpkg -i gitinspect_*_linux_amd64.deb
sudo rpm -i gitinspect_*_linux_amd64.rpm
sudo apk add gitinspect_*_linux_amd64.apk

Usage

Commands

gitinspect inspect [flags] <repo-path-or-url>   Inspect a repository
gitinspect serve [flags]                          Start HTTP server
gitinspect mcp                                     Start MCP server (for AI agents)
gitinspect version                                 Print version

Local Repository

gitinspect inspect /path/to/repo

Remote Repository

gitinspect inspect https://github.com/user/repo.git

With Options

gitinspect inspect --format text --max-tokens 10000 --strip /path/to/repo
gitinspect inspect --include "**/*.go" --exclude "**/vendor/*" .

HTTP Server Mode

gitinspect serve --port 8080 --api-key my-secret-key --max-concurrent 8

Then send a POST request:

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-secret-key" \
  -d '{"repo": "https://github.com/user/repo.git", "format": "json"}' \
  http://localhost:8080/inspect

Use --api-key to require authentication on all requests. Use --max-concurrent to control how many remote fetches run in parallel (default: 4).

AI Agent Integration (MCP)

gitinspect includes a built-in Model Context Protocol (MCP) server, making it directly invokable by AI coding agents.

Starting the MCP Server

gitinspect mcp

This starts an MCP server over stdio — the standard transport for AI agent integration.

Configuring in AI Agents

Add to your agent's MCP config file:

{
  "mcpServers": {
    "gitinspect": {
      "command": "gitinspect",
      "args": ["mcp"]
    }
  }
}

Works with Claude Desktop, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible agent.

MCP Tools

inspect_repo — Inspect a Git repo and return a structured snapshot with file contents, dependencies, and stats. Supports format, max_tokens, max_files, include, exclude, strip, no_cache parameters.

list_repo_files — List all files with priority scores and token estimates, without reading file contents. Useful for deciding which files to inspect before reading them.

CLI Flags

Flag	Default	Description
--format	json	Output format: json, text, yaml
--max-tokens	6000	Maximum token budget
--max-files	0	Maximum number of files (0 = unlimited)
--include	(none)	Include glob patterns (repeatable)
--exclude	(none)	Exclude glob patterns (repeatable)
--strip	false	Strip comments and blank lines
--no-cache	false	Disable cache
--quiet	false	Suppress progress output (for scripting)
--port	8080	HTTP server port (serve command)
--api-key	(none)	API key for HTTP server authentication
--max-concurrent	4	Maximum concurrent remote fetches

Output Examples

JSON (default)

gitinspect inspect --format json .

{
  "tree": {
    "README.md": "# my-project\nA cool project.\n",
    "main.go": "package main\n\nfunc main() {\n\tprintln(\"hello\")\n}\n",
    "go.mod": "module github.com/user/project\n\ngo 1.25\n"
  },
  "stats": {
    "file_count": 3,
    "total_bytes": 120,
    "total_tokens": 30,
    "truncated": false
  },
  "dependencies": [
    "github.com/go-git/go-git/[email protected]"
  ],
  "version": "0.1.0"
}

Text

gitinspect inspect --format text .

File: README.md
---
# my-project
A cool project.

File: go.mod
---
module github.com/user/project

go 1.25

File: main.go
---
package main

func main() {
        println("hello")
}

YAML

gitinspect inspect --format yaml .

tree:
  README.md: |
    # my-project
  go.mod: |
    module github.com/user/project
  main.go: |
    package main
stats:
  file_count: 3
  total_bytes: 120
  total_tokens: 30
  truncated: false
dependencies:
  - github.com/go-git/go-git/[email protected]
version: 0.1.0

File Priority

Files are sorted by priority before inclusion. Higher-priority files are included first within the token budget:

Priority	Files
4 (highest)	README*
3	main.*, cmd/*/main.*
2	go.mod, package.json, Cargo.toml, setup.py, Gemfile, requirements.txt
1	Makefile, Dockerfile, docker-compose.yml
0	All other files

Token Budget

Tokens are estimated as ceil(len(content) / 4). When the budget is exceeded:

1. Files are added in priority order
2. If a file would exceed the remaining budget, it is truncated (first 1000 + last 500 chars with a truncation marker)
3. If a single file alone exceeds the entire budget, it is included but truncated
4. stats.truncated is set to true in the output

Note: If --max-tokens is 0 or negative, it defaults to 6000.

Dependency Extraction

Supported manifest files:

File	Format	Example Output
go.mod	Go modules	github.com/go-git/go-git/[email protected]
package.json	Node.js	react@^18.0.0
Cargo.toml	Rust	[email protected]
requirements.txt	Python	flask==2.0
Gemfile	Ruby	rails

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache License 2.0 — See LICENSE for details.