# Clogmeter CLI & MCP server

**See what's clogging your AI agent.**

Offline CLI and [Model Context Protocol](https://modelcontextprotocol.io) stdio server that scans a repo for instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*.mdc`, `SKILL.md`, and similar), then reports:

- Per-file and per-section **token weight** (o200k_base via `gpt-tokenizer`)
- Share of common context windows (**32k / 128k / 200k**)
- Near-**duplicate** rules
- Opposing **always / never** conflicts

Nothing is uploaded. Analysis runs entirely on your machine.

Interactive browser inspector: [https://clogmeter.vercel.app](https://clogmeter.vercel.app)

## Install

```bash
# one-shot
npx clogmeter .

# or global
npm install -g clogmeter
clogmeter .
```

Requires **Node.js ≥ 18**.

## CLI

```bash
npx clogmeter [path]       # scan repo (default: cwd)
npx clogmeter --json [path]
npx clogmeter --help
npx clogmeter mcp          # start MCP stdio server
```

Example:

```text
Clogmeter — instruction file scan
Root: /path/to/repo

Total: 1,234 tokens  (5,678 chars, 3 files)
Windows: 3.9% of 32k  |  1.0% of 128k  |  0.6% of 200k

FILE                          TOKENS   %TOT   %32k  %128k  %200k
----------------------------------------------------------------
AGENTS.md                        800  64.8%   2.5%   0.6%   0.4%
CLAUDE.md                        300  24.3%   0.9%   0.2%   0.2%
.cursor/rules/style.mdc          134  10.9%   0.4%   0.1%   0.1%

…

Full interactive report: https://clogmeter.vercel.app
```

## MCP server

Start over stdio:

```bash
npx clogmeter mcp
# or
npx clogmeter-mcp
```

### Tools

| Tool | Args | Purpose |
| --- | --- | --- |
| `scan_instruction_files` | `path?` | Scan a directory (or one file) and return the full report JSON + site link |
| `analyze_instruction_text` | `text`, `filename?` | Analyze raw instruction text without reading disk |

### Claude Code

Add to your Claude Code MCP settings (e.g. `~/.claude.json` / project `.mcp.json`):

```json
{
  "mcpServers": {
    "clogmeter": {
      "command": "npx",
      "args": ["-y", "clogmeter", "mcp"]
    }
  }
}
```

### Cursor

Cursor → Settings → MCP → Add server, or in `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "clogmeter": {
      "command": "npx",
      "args": ["-y", "clogmeter", "mcp"]
    }
  }
}
```

### Claude Desktop

Edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "clogmeter": {
      "command": "npx",
      "args": ["-y", "clogmeter", "mcp"]
    }
  }
}
```

(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json`)

## MCP Registry

- Registry name: `io.github.clogmeter/clogmeter`
- `package.json` includes `"mcpName": "io.github.clogmeter/clogmeter"`
- Metadata lives in [`server.json`](./server.json)

Publish flow (after this package is on npm):

```bash
npm publish --access public
# install mcp-publisher, then:
mcp-publisher login github
mcp-publisher publish
```

## Privacy

- Fully **offline**
- **No network calls** from the CLI or MCP tools
- Tokenization and duplicate/conflict heuristics run locally

## Related

- Web app: [clogmeter.vercel.app](https://clogmeter.vercel.app)
- VS Code / Cursor extension: [clogmeter.clogmeter](https://marketplace.visualstudio.com/items?itemName=clogmeter.clogmeter)
- Source: [github.com/Clogmeter/clogmeter-mcp](https://github.com/Clogmeter/clogmeter-mcp)

## License

MIT © Clogmeter