---
name: gitpulse-insights
description: Read GitPulse repository insights over MCP — worktrees, agent sessions, uncommitted changes, overlapping dirty files, ledger verdicts, and code-graph availability. Use when an agent needs a honest snapshot of a checkout before editing, when multiple worktrees or coding agents are in flight, or when the user asks what is happening in a GitPulse-managed repo.
license: MIT
compatibility: Requires the gitpulse-mcp binary on PATH and an absolute git repository path.
metadata:
  mcp-protocol: "2026-07-28"
  agent-plugins: "1.0.0"
---

# GitPulse insights

GitPulse's MCP server never touches git state: it does not check out a branch, write a file in your repository, or take a task lease. Its read tools (`gitpulse_insights`, `gitpulse_status`, `gitpulse_ledger_events`, and the rest of the `readOnlyHint` set) create and migrate nothing. The server does have five write tools, and they change only the GitPulse task board: `gitpulse_add_task`, `gitpulse_import_tasks`, `gitpulse_complete_task`, `gitpulse_delete_task` and `gitpulse_merge_tasks`. Ask it what is true, then mutate through the agent that already holds the writer lease.

It surfaces GitPulse-owned facts and selected **DevCouncil** modules (in-process DevMap). Policy and agent hosting go through **Manvi**, not this server.

## Before you edit

1. Call `gitpulse_insights` with the absolute `repo_path`.
2. Read every facet's `ok` / `error` / `available` field. An empty list with `ok: false` means the check did not run — not that the repository is clean.
3. If `collisions.overlapping_files > 0`, or `collisions.unscanned_worktrees > 0`, or `collisions.shared_worktree_files > 0`, call `gitpulse_collision_risk` and `gitpulse_change_context` for the worktree you are about to touch.
4. Prefer `gitpulse_change_context` over guessing the branch, dirty files, or parked merge/rebase of a worktree.

## Tool map

| Tool | When |
| --- | --- |
| `gitpulse_insights` | First look at a repo |
| `gitpulse_change_context` | About to edit one worktree |
| `gitpulse_collision_risk` | Parallel agents or several worktrees |
| `gitpulse_active_changes` | Need the file list, not just counts |
| `gitpulse_status` | Narrower status (ledger + worktrees + codeintel) |
| `gitpulse_ledger_events` | Policy verdicts and recorded mutations |
| `gitpulse_task_view` | DevCouncil tasks and leases, when a store exists |
| `gitpulse_codeintel_*` | Symbol search, impact, dependencies, trace, dead symbols |
| `devmap_*` (11 tools: `status`, `search`, `dependencies`, `impact`, `trace`, `neighbors`, `dead_symbols`, `clones`, `preview`, `explore`, `affected_tests`) | The same code graph under DevMap's own tool names, for parity with the standalone `devmap mcp` server; pass `repo_path` on every call |
| `gitpulse_add_task`, `gitpulse_import_tasks`, `gitpulse_complete_task`, `gitpulse_merge_tasks`, `gitpulse_delete_task` | The only write tools: they change the task board, never git (see the gitpulse-tasks skill) |
| `gitpulse_provenance` | Verification freshness for a commit, and where it sits relative to the base (`landed_on_base`, `ahead`, `behind`) |

## Honesty rules this server already enforces

- Unscanned worktrees are counted, never implied clean.
- A missing code graph is `available: false` with a reason, not an empty hit list.
- Agent worktrees are recognised from `/.<agent>/worktrees/` layout, never from a branch name.
- `agents.ok: false` is "the worktree listing failed", not "no agents"; `agents.truncated: true` means the counts came from a capped sample, so `agents.sessions` is a floor and a kind whose worktrees all fall past the cap is absent from `agents.kinds` rather than undercounted.
- An agent worktree is a *checkout*, not a running process: `agents.kinds` counts the sessions a repository has on disk and cannot tell a running one from one abandoned mid-change. `agents.live` can: it lists the running Claude Code sessions per worktree with their status. A kind that keeps no readable registry (Codex) is reported with `ok: false` and an error, so a zero there means "could not count", not "none".

Pass `repo_path` as an absolute filesystem path on every call. The protocol is MCP `2026-07-28`: include `_meta.io.modelcontextprotocol/protocolVersion` and `clientCapabilities` on each request. Legacy `initialize` still works for older clients.