Installation

import { Aside, Tabs, TabItem } from ‘@astrojs/starlight/components’;

1. Install the binary

cargo install gl-cli

Or download a pre-built binary from GitHub releases.

2. Index your project

cd your-project
gl init .

This creates .gl/ and starts indexing. On large projects, keep it live while you work:

gl watch . &

Check that it worked:

gl stats -p .
# nodes: 1842  edges: 4391  files: 203

3. Connect your AI client

Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "ganglia": {
      "command": "gl",
      "args": ["mcp", "-p", "."]
    }
  }
}
```

Restart Claude Code. You'll see `ganglia` in the MCP tools list.

Open **Settings → MCP** and add:

```json
{
  "ganglia": {
    "command": "gl",
    "args": ["mcp", "-p", "/absolute/path/to/your/project"]
  }
}
```

Use the absolute path — Cursor doesn't resolve `.` relative to the project.

Open **Settings → MCP Servers** and add:

```json
{
  "mcpServers": {
    "ganglia": {
      "command": "gl",
      "args": ["mcp", "-p", "/absolute/path/to/your/project"]
    }
  }
}
```

Any MCP-compatible client works. Use:

- **command:** `gl`
- **args:** `["mcp", "-p", "/path/to/project"]`
- **protocol:** stdio

The server speaks standard MCP over stdin/stdout.

4. Verify it works

Open your AI client and ask:

What are the most-called functions in this project?

If Ganglia is connected, it will call code_hotspots and return a ranked list — not a file listing. That’s how you know it’s working.

Backends

Ganglia uses Cozo (embedded SQLite) by default — zero setup, no Docker.

If you want the live web dashboard:

docker run -p 6379:6379 falkordb/falkordb
gl init . --backend falkor
gl serve   # opens dashboard at localhost:3000

Process management

gl mcp is a long-running process. Ganglia manages it automatically:

Single instance per project — on startup, any stale MCP process for the same project is killed before the new one takes over. You won’t accumulate zombie instances across sessions.
Idle auto-exit — the process exits after 30 minutes of inactivity. Override with GL_IDLE_TIMEOUT_SECS=<seconds> in the MCP server environment (set 0 to disable).
Clean signal handling — SIGTERM and SIGINT trigger a graceful shutdown on Unix.

To manually kill an MCP instance:

gl kill              # kill MCP for the current project
gl kill -p /path     # kill MCP for a specific project
gl kill --all        # kill all known project instances

Updating

cargo install gl-cli --force

Troubleshooting

gl: command not found — make sure ~/.cargo/bin is in your $PATH.

MCP tools not showing — confirm gl stats -p . shows nodes > 0. If zero, run gl watch . & and wait 30 seconds.

Cursor/Windsurf not connecting — use the absolute path in args, not ..