repo-pulse

repo-pulse-mcp

Turn git history into answers your AI assistant can act on: what is risky in this branch, who should review it, which files keep breaking and what changed since the last release.

repo-pulse is a read-only Model Context Protocol server for local git repositories. It runs over stdio, needs nothing but Node.js and git, never modifies a repository and never touches the network. Ask your assistant things like:

• 🔍 "I'm about to open a PR. What's risky, what did I forget, and who should review it?"
• 🐛 "Which files keep breaking? Where is the churn?"
• 👥 "Who knows the billing module best? Are we depending on a single person?"
• 🔗 "Which files always change together with this one?"
• 🚀 "What changed since the last release? Draft the release notes."
• 🧹 "Which branches are stale, and which are already merged?"

It works with any local git repository, whether it was cloned from GitHub, GitLab, Bitbucket or anywhere else, or has no remote at all. Platform data such as pull requests, issues or CI status is out of scope.

A real Claude Code session reviewing a branch of vitejs/vite with no shell, only repo-pulse. See how it was recorded.

Quick start

Requires Node.js 22.12+ and git. There is nothing to clone or build: the server runs from npm.

# Claude Code: run inside the repository you want to ask about
claude mcp add repo-pulse -- npx -y repo-pulse-mcp --repo "$PWD"

Then ask "What changed since the last release?", or review your branch with the built-in prompt: /mcp__repo-pulse__review_branch main. For Claude Desktop and other MCP clients, see Installation.

Features

13 tools, grouped by the question they answer. 🆕 marks the newest ones.

🔍 Code review and risk

👥 Ownership and team

🚀 Releases and branches

🕒 History and activity

📦 Also included

All tools are annotated readOnlyHint: true, declare an outputSchema, and return both structuredContent and a JSON text block for older clients. Full inputs and outputs are in the Tool reference.

Example conversations

You: I'm about to open a PR for feature/search. Anything I should know?

Assistant (calls review_context with base: "main", head: "feature/search"): 4 commits touching 6 files. src/api.ts is the risky one: it changed 14 times on main in the last six months and 6 of those were bug fixes. You may have forgotten test/api.test.ts: it changed together with src/api.ts in 9 of 10 commits but is not in this branch. Suggested reviewer: Alice, who holds most of the recent knowledge of these files.

You: Who knows src/billing/ best? Are we depending on one person?

Assistant (calls knowledge_map with path: "src/billing"): The bus factor is 1. Carol holds 72% of the recent knowledge and is the main owner of 11 of 14 files; 9 of them depend on her alone. Bob is a distant second at 18%. Pairing Bob with Carol on the next billing change would spread the knowledge…

You: Which parts of the code has nobody touched in a long time?

Assistant (calls code_age with minAgeDays: 365): Half of the files haven't changed in 18 months. src/legacy/ is the oldest directory (median 3.2 years), and 41 of its files were last changed by people who no longer commit here. That's where knowledge is being lost…

You: Where is the churn this quarter, and what keeps breaking?

Assistant (calls file_hotspots with days: 90): src/core/insights.ts changed in 23 commits by 3 people, far more than anything else, and 9 of those commits were fixes. That's a good candidate for splitting up or adding tests…

You: What changed since the last release?

Assistant (calls release_notes_draft with defaults: latest tag → HEAD): Since v0.2.0 there are 14 commits. One breaking change: the config file moved to repo-pulse.json. New features: an author filter for activity and branch merge detection. Three bug fixes, mostly around empty repositories. Here's a Markdown draft you can paste into the GitHub release: …

You: Can we clean up some branches?

Assistant (calls stale_branches with days: 30): 6 branches haven't seen a commit in 30+ days. 4 of them are already merged into main and are safe to delete: …

You: (selects the weekly_engineering_update prompt)

Assistant (calls recent_activity, contributor_summary, file_hotspots, stale_branches): Highlights — …

The conversations are illustrative: names and numbers are made up.

And a real session on vite, asking about unreleased changes and stale branches:

Why repo-pulse?

There are already MCP servers for GitHub, GitLab and git itself, and coding agents with a shell can run git log directly. repo-pulse does not try to replace them. It does a different job: it turns local git history into answers and is safe to auto-approve.

What that means in practice:

• Fewer steps, correct numbers. Questions like "where is the churn?", "what goes into the release notes?" or "which branches are merged and stale?" otherwise take several shell commands and hand-written counting pipelines, which can be silently wrong. repo-pulse does the counting in tested code and returns deterministic JSON that says which filters it applied. Some tools go further than any single git command: review_context combines churn, fix history, change coupling and ownership for a branch in one call.
• Read-only you can verify. Every tool is annotated readOnlyHint and backed by a git subcommand allowlist (see Security model), so a client can run it without asking for approval each time. You would not give the same permission to a shell or to a git server that can commit and push.
• Useful where there is no shell. Chat clients such as Claude Desktop cannot run git. With repo-pulse, an engineering manager or tech lead can ask about a repository directly.
• Works with anything git can open. It works offline and in air-gapped environments, on self-hosted or remote-less repositories, and it never returns author email addresses.

Use it alongside a platform server, not instead of one. Pair it with the GitHub or GitLab MCP when you also need pull requests, issues or CI status. If you work in a coding agent that already has a shell and you only need the occasional git log, you probably do not need repo-pulse.

Benchmark

Claude Code (Sonnet 5.5) answered the same four questions about vite and express twice: once with only a read-only shell and once with only repo-pulse. Full method, answers and caveats are in bench/README.md.

The benchmark was run with v0.3.0 (10 tools). The honest summary: repo-pulse is not cheaper in tokens for simple one-off questions, because a good model writes compact shell pipelines and repo-pulse's tool definitions cost tokens in every session (about 4k for the current 13 tools). It wins on multi-step questions, on getting the numbers right, and in clients that have no shell at all.

Requirements

• Node.js 22.12+
• git 2.24+ (for --end-of-options)

Installation

The package is published on npm, so there is nothing to clone or build. The server only serves repositories you explicitly allow. Pass them as CLI arguments or an environment variable (separated by : on macOS/Linux, ; on Windows):

npx -y repo-pulse-mcp --repo ~/code/my-app --repo ~/code/my-lib
# or, as plain arguments
npx -y repo-pulse-mcp ~/code/my-app ~/code/my-lib
# or
REPO_PULSE_REPOS=~/code/my-app:~/code/my-lib npx -y repo-pulse-mcp

Without any configured repository the server refuses to start. It is also listed in the MCP Registry as io.github.hasanyelaldi/repo-pulse-mcp.

Choosing tools

Every enabled tool's definition costs tokens in every session, about 4k for all 13. If you only need some of them, enable just those with --tools (or REPO_PULSE_TOOLS), using the groups from Features, single tool names, or both:

npx -y repo-pulse-mcp --repo ~/code/my-app --tools review,list_tags
# or
REPO_PULSE_TOOLS=review,ownership npx -y repo-pulse-mcp ~/code/my-app

An unknown name stops the server at startup with the list of valid names. Prompts follow the tools: review_branch needs review_context, release_notes needs release_notes_draft, ownership_report needs knowledge_map, cleanup_branches needs stale_branches, and weekly_engineering_update needs the four tools it uses.

Claude Code

Run this inside the repository you want to ask about:

claude mcp add repo-pulse -- npx -y repo-pulse-mcp --repo "$PWD"

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart Claude Desktop. Use absolute paths:

{
  "mcpServers": {
    "repo-pulse": {
      "command": "npx",
      "args": ["-y", "repo-pulse-mcp", "--repo", "/absolute/path/to/your/repository"]
    }
  }
}

From source

git clone https://github.com/hasanyelaldi/repo-pulse-mcp.git
cd repo-pulse-mcp
npm ci
npm run build
node build/index.js --repo /absolute/path/to/your/repository

Podman / Docker

podman build -t repo-pulse-mcp .
podman run -i --rm \
  -v "$PWD:/repos/project:ro" \
  -e REPO_PULSE_REPOS=/repos/project \
  repo-pulse-mcp

The repository is mounted read-only. On SELinux hosts (Fedora, RHEL) add ,Z to the volume options. Replace podman with docker if you prefer; the image uses no Docker-specific features. For an MCP client, use podman as the command and the rest as args.

Tool reference

Every tool accepts an optional repo argument: a repository name (the directory name, shown in the overview resource) or its absolute path. It defaults to the first configured repository.

Results are compact JSON, and commit lists carry shortHash (git's abbreviated hash, long enough to be unambiguous in the repository) rather than the full hash; it works anywhere a ref is accepted.

review_context

Output: { repo, base, head, baseCommit, headCommit, windowDays, commits, truncated, changeAuthors, filesChanged, additions, deletions, historyScanned, scanTruncated, files: [{ path, additions, deletions, changes, fixes, lastChanged, owner, ownerShare }], missingCompanions: [{ path, coupledWith, sharedCommits, degree }], reviewers: [{ author, share, filesKnown, lastCommit }] }

One call that combines file_hotspots, change_coupling and knowledge_map for the files changed in base..head, read against the history of base:

• files are the changed files, riskiest first: most fixes on base, then most changes. New files have no history, so changes is 0 and owner is null.
• missingCompanions are files that were not changed but usually change together with a changed file (same degree as change_coupling), such as a test or config that may have been forgotten.
• reviewers are ranked by recent-weighted knowledge of the changed files and leave out the authors of the changes themselves. share is relative to everyone's knowledge, change authors included.

The changed files come from the non-merge commits in base..head, so a file that was changed and later changed back still counts. Commits touching more than maxFilesPerCommit files still count toward changes and fixes, but not toward ownership or coupling. Renames are not followed.

file_hotspots

Output: { repo, windowDays, types, commitsScanned, scanTruncated, commitsMatched, fixesFromKeywords, filesChanged, hotspots: [{ path, changes, fixes, additions, deletions, authors, lastChanged }] }

Merge commits are excluded and renames are not followed, so a renamed file starts fresh. Use file_history to trace a single file across renames.

fixes counts the commits among changes that were bug fixes: a file that changes often and mostly through fixes is a better refactoring candidate than one that just grows. With types: ["fix"] only fixes are counted, so the ranking shows the files that keep breaking. Commit types come from conventional-commit headers (fix(api): …). A commit without one counts as a fix when its subject mentions "fix", "bug" or "hotfix"; fixesFromKeywords says how many fixes were found that way, so a non-zero value means the counts are an estimate. A header always wins, so docs: fix typo is not a fix.

change_coupling

Output: { repo, windowDays, commitsScanned, scanTruncated, commitsSkipped, pairCount, pairs: [{ fileA, fileB, sharedCommits, revisionsA, revisionsB, degree }] }

degree is the number of shared commits as a percentage of the average number of commits that touched each file: 100 means the two files always change together. A high degree between files that do not import each other usually points to a hidden dependency (duplicated logic, a config or fixture that must be kept in sync). Large commits such as bulk renames or formatting runs are skipped because they would couple every file they touch. Merge commits are excluded and renames are not followed.

knowledge_map

Output: { repo, path, windowDays, halfLifeDays, commitsScanned, scanTruncated, commitsSkipped, filesAnalyzed, busFactor, concentratedFiles, authors: [{ author, share, filesOwned, commits, lastCommit }], files: [{ path, owner, ownerShare, authors, commits, lastChanged }] }

Every commit that touches a file gives its author knowledge of that file, halved every halfLifeDays, so someone who reworked a module last month outranks someone who wrote it three years ago. Line counts are ignored so generated or reformatted diffs do not dominate. share and ownerShare are percentages. busFactor is the fewest authors who together hold more than half of the knowledge in the area; concentratedFiles counts files where one author holds at least 80%. files lists the most frequently changed files first with their main owner, which makes it a quick reviewer suggestion for a path. Merge commits are excluded and renames are not followed.

code_age

Output: { repo, path, inactiveDays, commitsScanned, scanTruncated, filesOnHead, medianAgeDays, ageBuckets: [{ label, files }], inactiveAuthorFiles, directories: [{ path, files, medianAgeDays, newestAgeDays }], files: [{ path, lastChanged, ageDays, lastAuthor, lastAuthorActive, commits }] }

Every file on HEAD gets the date and author of the last non-merge commit that changed it. ageBuckets splits the files into under 30 days, 30–90 days, 90 days–1 year, 1–2 years and over 2 years. directories groups files by the first directory level below path (. for files directly in it), oldest median first, which shows the parts of the code nobody works on any more. lastAuthorActive is false when that person has not committed anywhere in the repository for inactiveDays, merges included; inactiveAuthorFiles counts those files, a rough measure of knowledge that has left. People who commit under several names with one email are counted once.

Which files are on HEAD comes from additions and deletions along the first-parent history, so files that a merge added or deleted by itself are handled correctly. History is read up to 20,000 commits; beyond that scanTruncated is true and files last changed before the cut-off are missing.

contributor_summary

Output: { repo, windowDays, totalCommits, scanTruncated, contributorCount, contributors: [{ author, commits, firstCommit, lastCommit }] }

release_notes_draft

Output: { repo, from, to, commitCount, truncated, markdown?, sections?: [{ key, title, entries: [{ shortHash, scope, description, author }] }] }

markdown is a ready-to-paste draft; sections is the same content as structured data. Only the requested format is returned, because both together double the size of the result.

Sections, in order: Breaking Changes, Features, Bug Fixes, Performance, Refactoring, Documentation, Tests, Build System, Continuous Integration, Chores, Reverts, Other Changes. A commit is breaking if its header has ! (feat!: …) or its body has a BREAKING CHANGE: footer; breaking commits also appear in their type section. Merge commits are skipped.

list_tags

Output: { repo, totalTags, latestOnHead, commitsSinceLatest, tags: [{ name, date, shortHash, subject }] }

Tags are sorted by tag date, newest first. latestOnHead is the latest tag reachable from HEAD, which can differ from the newest tag when maintenance releases are tagged on other branches. commitsSinceLatest counts the commits after it, i.e. unreleased work.

compare_refs

Output: { repo, base, head, baseCommit, headCommit, ahead, behind, status, truncated, aheadCommits: [{ shortHash, author, date, subject }], behindCommits: [...] }

ahead counts commits reachable from head but not base, behind the reverse. status is identical, ahead, behind or diverged. Both refs go through the same validation as release_notes_draft, and the counts include merge commits.

stale_branches

Output: { repo, thresholdDays, totalBranches, staleCount, branches: [{ name, lastCommitDate, lastAuthor, daysSinceLastCommit, mergedIntoHead }] }

recent_activity

Output: { repo, windowDays, totalCommits, truncated, commits: [{ shortHash, author, date, subject }] }

commit_search

Output: { repo, query, windowDays, totalMatches, truncated, commits: [{ shortHash, author, date, subject }] }

file_history

Output: { repo, path, commitCount, truncated, renamed, commits: [{ shortHash, author, date, subject, path, additions, deletions }] }

Renames are followed, so older commits report the path the file had at the time and renamed is true when the listed commits span more than one path. Merge commits are skipped; additions and deletions are null for binary files.

Resource: repo://{name}/overview

One resource per configured repository (listed via resources/list, name completion supported):

{
  "name": "my-app",
  "path": "/home/me/code/my-app",
  "currentBranch": "main",
  "detachedHead": false,
  "lastCommit": { "hash": "…", "shortHash": "1a2b3c4", "author": "…", "date": "…", "subject": "…" },
  "latestTag": "v0.2.0",
  "commitCount": 412,
  "branchCount": 7,
  "tagCount": 9
}

Prompt: review_branch

Arguments (strings): base (required, e.g. main), head (default HEAD), repo. In Claude Code it is a slash command:

/mcp__repo-pulse__review_branch main feature/search

It tells the model to call review_context (and compare_refs, when that tool is enabled) and write a review briefing: summary, risky files, possibly missing files, suggested reviewers and a checklist of things to verify. It also tells the model that repo-pulse returns history, not the diff, so the briefing does not claim to have read the code. Available whenever review_context is enabled.

Prompt: release_notes

Arguments (strings, all optional): from (default: the latest tag before to), to (default HEAD), version, repo. In Claude Code:

/mcp__repo-pulse__release_notes

It tells the model to call release_notes_draft and rewrite the grouped commits as user-facing release notes: breaking changes first, then features and fixes, with internal chores left out. Without version, it also calls list_tags (when enabled) and suggests the next semver version. Available whenever release_notes_draft is enabled.

Prompt: ownership_report

Arguments (strings, both optional): path (default: the whole repository), repo. In Claude Code:

/mcp__repo-pulse__ownership_report src/billing

It tells the model to call knowledge_map and write a report on the owners, the bus factor and the files that depend on a single person, ending with concrete recommendations. When code_age and file_hotspots are enabled it also calls them, to flag files last changed by people who have left and hotspots owned by one person. Available whenever knowledge_map is enabled.

Prompt: cleanup_branches

Arguments (strings, both optional): days (default 30), repo. In Claude Code:

/mcp__repo-pulse__cleanup_branches

It tells the model to call stale_branches and split the result into merged branches that are safe to delete, with one git branch -d command each, and unmerged branches that need a decision, with their last author. The model is told not to run the commands itself. Available whenever stale_branches is enabled.

Prompt: weekly_engineering_update

Arguments (strings, both optional): repo, days (default 7). Produces a user message that tells the model which tools to call and how to structure a short stakeholder update.

Security model

The server is designed so that a confused or manipulated model cannot do damage:

• Strictly read-only. git runs through a single function that only allows log, rev-list, rev-parse, describe and for-each-ref. Anything else is rejected before a process starts.
• No shell, ever. git is started with child_process.execFile and an argument array, so arguments are never interpreted by a shell.
• Repository allowlist. Only repositories passed via --repo / REPO_PULSE_REPOS are served. Paths are canonicalized with realpath (symlinks resolved) at startup and compared exactly; unknown repositories get the same error whether or not they exist on disk. If nothing is configured, the server does not start (fail closed).
• Input validation. All inputs go through zod schemas with bounds. Refs must look like a branch, tag, hash or ~N/^N suffix: no leading -, no .. ranges, no @{} or : syntax, and they are passed after --end-of-options, then resolved with rev-parse --verify. Paths must be relative without .. segments and are passed after -- with --literal-pathspecs (no globbing). Author filters use --fixed-strings, so they are not regexes.
• Bounded work. Result counts are capped per tool, scans stop at 5,000 commits, git output is capped at 16 MB, and every git call times out after 15 s. Truncation is reported in the output.
• Hardened git environment. Inherited GIT_* variables (e.g. GIT_DIR) are dropped, prompts are disabled, optional locks are off, core.fsmonitor is forced off (a repository's own config could otherwise make git run a program), and external diff/textconv drivers are disabled where diffs are computed.
• Less personal data. Only author names are returned, never email addresses.

Out of scope: the server trusts the git binary on PATH and the repositories you allowlist. It is a local developer tool; it has no network transport and no authentication.

Architecture

src/
├── index.ts              # stdio entry point: config → registry → server → transport
├── server.ts             # MCP layer: tools, resource and prompt with zod schemas
├── config.ts             # --repo / REPO_PULSE_REPOS parsing, repo allowlist (RepoRegistry)
├── errors.ts             # InputError (safe to show) and GitError
├── core/
│   ├── insights.ts       # one method per feature: builds git args, aggregates results
│   ├── glob.ts           # exclude globs, matched in-process on paths git returned
│   └── release-notes.ts  # pure conventional-commit parsing, grouping and Markdown
└── git/
    ├── runner.ts         # the only place that spawns processes (allowlist, limits, env)
    ├── parsers.ts        # pure parsers for git output (no I/O)
    └── validation.ts     # ref / path / author validation

Design notes:

• Process I/O is isolated from parsing. runner.ts is the only module that spawns processes; parsers.ts and release-notes.ts are pure functions tested with string fixtures.
• Unambiguous output format. git output uses ASCII unit (0x1f) and record (0x1e) separators instead of tabs or newlines, which can appear in commit subjects and file names.
• Testable composition. createServer() takes its dependencies (allowlist, git runner, clock) as arguments, so tests connect it to an in-memory transport with a fixed "now".
• Errors become tool results. Validation and git failures surface as isError: true tool results with an actionable message, so the model can correct itself instead of the session failing.
• stdout is sacred. It carries JSON-RPC, so logging goes to stderr and ESLint forbids console.log.

Built on the official MCP TypeScript SDK v2 (@modelcontextprotocol/server).

Development

npm ci
npm run dev -- --repo .     # run from source with tsx
npm test                    # unit + integration tests (vitest)
npm run lint                # ESLint
npm run format              # Prettier
npm run typecheck
npm run build               # compile to build/
npm run check               # everything CI runs
npm run inspect             # build first; opens MCP Inspector against this repository

Releasing. Bump the version in package.json, server.json (both version fields) and SERVER_VERSION in src/server.ts (a unit test fails if they differ), merge, then push a tag: git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z. The release workflow runs the full check, publishes to npm with provenance and registers the new version in the MCP Registry. Both use GitHub OIDC (npm Trusted Publishing and the registry's github-oidc login), so no publishing token is stored. If only the registry step fails, run the workflow manually (gh workflow run release.yml): it skips npm and retries the registry.

Tests. Unit tests cover the parsers, validation, config parsing and release-notes grouping. Integration tests create a temporary git repository with a scripted history (fictional authors, fixed dates) and exercise every feature, both directly and end to end through a real MCP client over an in-memory transport, including the security checks.

MCP Inspector. npm run build && npm run inspect opens the Inspector web UI connected to this repository. For scripted checks, the CLI mode works too:

npx @modelcontextprotocol/inspector --cli node build/index.js -e REPO_PULSE_REPOS="$PWD" \
  --method tools/call --tool-name release_notes_draft

Limitations and ideas

• Activity, hotspot and contributor tools look at commits reachable from HEAD; work on unmerged branches is not counted.
• Renames are not followed in file_hotspots, change_coupling, knowledge_map, review_context and code_age: a renamed file counts as new from the rename on.
• Each session pays about 4k tokens for the tool definitions, so on simple one-off questions a shell can be cheaper (see Benchmark). Choosing tools cuts this to the groups you use.
• Possible next steps: an HTTP transport for team use.

License

MIT