gitsem 0.4.1

Semantic search and spatial navigation for Git repositories — map, get, and grep for AI coding agents
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# MCP Server Setup

`git-semantic mcp` starts a JSON-RPC server over stdio that exposes `map`, `get`, `grep`, and `health` as tools to any MCP-compatible client.

```bash
git-semantic mcp
```

---

## Claude Code

Add to `.claude/settings.json` in your project (or `~/.claude/settings.json` for all projects):

```json
{
  "mcpServers": {
    "git-semantic": {
      "command": "git-semantic",
      "args": ["mcp"]
    }
  }
}
```

Or use the built-in setup command:

```bash
git-semantic enable claude
```

This installs a `@git-semantic` subagent at `.claude/agents/git-semantic.md` that Claude invokes automatically when navigating code.

---

## Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "git-semantic": {
      "command": "git-semantic",
      "args": ["mcp"]
    }
  }
}
```

---

## Windsurf / Codex / other MCP clients

The server speaks standard MCP (JSON-RPC over stdio). Any client that supports MCP tool calls works. Point the client at:

```
command: git-semantic
args: ["mcp"]
```

---

## Available tools

| Tool | Description |
|---|---|
| `map` | Orient to a task — returns the relevant semantic community with file locations |
| `get` | Read a file by path (with outline/signatures/full modes) or an exact chunk by range |
| `grep` | Hybrid BM25 + semantic search — natural language or exact identifiers |
| `health` | Community heatmap — cohesion, coupling, fan-in per cluster |

---

## Prerequisites

The index must exist before the MCP server can serve queries. Run once:

```bash
git-semantic index    # or: git fetch origin semantic && git-semantic hydrate
```