Skip to content

Setup Guide

Jump to bottom
github-actions[bot] edited this page May 18, 2026 · 5 revisions

Setup Guide

First-time setup for NeuralMind on any platform in under 5 minutes.

NeuralMind is a two-phase token optimizer for AI coding agents: a 4-layer semantic index that answers code questions in ~800 tokens, plus PostToolUse hooks that compress Read/Bash/Grep output before your agent sees it. Typical combined reduction is 5–10× vs baseline Claude Code / Cursor / any-LLM usage.

See Use Cases if you're unsure whether NeuralMind fits your workflow, or Comparisons for how it differs from Cursor @codebase, Copilot, Claude Projects, long context, and others.

Table of Contents

Install — pick your path

NeuralMind installs five ways. They all deliver the same package; pick the one that fits your existing tooling.

Method Command When to pick
pip pip install neuralmind graphifyy Default. Drops it in your active env.
pipx pipx install neuralmind && pipx inject neuralmind graphifyy Global CLI, no env pollution.
uv uv pip install neuralmind graphifyy Modern, fast Python tooling.
Docker docker pull ghcr.io/dfrostar/neuralmind:latest && docker run --rm -v "$PWD:/project:ro" ghcr.io/dfrostar/neuralmind:latest neuralmind --help Containerized — no Python on the host. Multi-platform (linux/amd64 + linux/arm64); auto-published to GHCR on every release since v0.9.0. To build locally instead: docker build -t neuralmind:dev . and substitute that tag.
From source git clone https://github.com/dfrostar/neuralmind && pip install -e . Contributing or hacking.

Pros and cons of each path, including persistence and PATH behavior: Install paths walkthrough.

Verify any install:

python -c "import neuralmind; print(neuralmind.__version__)"
neuralmind --help

30-Second Setup

Once installed (any path above):

# 1. Go to your project
cd /path/to/your-project

# 2. Generate the knowledge graph
graphify update .

# 3. Build the neural index
neuralmind build .

# 4. Test it
neuralmind wakeup .

You should see a compact project overview. If you do, NeuralMind is ready.

Choose Your Workflow

Your tool What to set up Guide
Claude Code CLI + PostToolUse hooks + MCP Claude Code
Claude Desktop MCP server Claude Desktop
Cursor / Cline / Continue MCP server Cursor / Cline / Continue
ChatGPT / Gemini / any LLM CLI (copy-paste output) Any LLM

Platform Setup

Claude Code

Claude Code gets the full two-phase optimization: smart retrieval and compressed tool outputs.

pip install neuralmind graphifyy

cd your-project
graphify update .
neuralmind build .

# Install PostToolUse compression hooks (compresses Read/Bash/Grep output)
neuralmind install-hooks .

# Optional: auto-rebuild index on every git commit
neuralmind init-hook .

Use it:

Inside a Claude Code session, call NeuralMind tools directly:

neuralmind_wakeup(".")          # project overview at session start
neuralmind_query(".", "How does auth work?")   # focused context
neuralmind_skeleton("src/auth.py")             # compact file view

Or add a .mcp.json at your project root so Claude Code loads NeuralMind automatically:

{
  "mcpServers": {
    "neuralmind": {
      "command": "neuralmind-mcp",
      "args": ["."]
    }
  }
}

Claude Desktop

pip install neuralmind graphifyy

cd your-project
graphify update .
neuralmind build .

Add NeuralMind to your Claude Desktop config:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json 
{
  "mcpServers": {
    "neuralmind": {
      "command": "neuralmind-mcp",
      "args": ["/absolute/path/to/your-project"]
    }
  }
}

Restart Claude Desktop. NeuralMind tools (neuralmind_wakeup, neuralmind_query, etc.) will appear automatically.

Tip: If NeuralMind is installed in a virtual environment, use the full path: "/path/to/venv/bin/neuralmind-mcp"

Cursor / Cline / Continue

pip install neuralmind graphifyy

cd your-project
graphify update .
neuralmind build .

Add to your MCP config (location varies by tool — check your tool's docs):

{
  "mcpServers": {
    "neuralmind": {
      "command": "neuralmind-mcp"
    }
  }
}

When using MCP tools, always pass the project_path parameter pointing to your project root.

Any LLM (copy-paste)

No special integration needed. Just pipe CLI output into your chat interface.

# Copy project overview (macOS)
neuralmind wakeup . | pbcopy

# Copy project overview (Linux)
neuralmind wakeup . | xclip -selection clipboard

# Copy project overview (Windows PowerShell)
neuralmind wakeup . | Set-Clipboard

# Ask a specific question and copy the answer
neuralmind query . "How does the payment system work?" | pbcopy

Paste the output at the start of any Claude/ChatGPT/Gemini conversation.

Keeping the Index Fresh

Option A — Git hook (recommended for active projects)

# Install managed hook (idempotent, coexists with other hooks)
neuralmind init-hook .

The index rebuilds automatically after every commit.

Option B — Manual

# After code changes
graphify update .
neuralmind build .

Option C — Scheduled (CI/CD or cron)

# .github/workflows/update-neuralmind.yml
- run: pip install neuralmind graphifyy
- run: graphify update .
- run: neuralmind build .

Verify Everything Works

# Check version
neuralmind --help

# Check index stats
neuralmind stats .

# Run token-reduction benchmark
neuralmind benchmark .

Expected output from stats:

Project: your-project
Built: True
Nodes: <number>

If Built: False, run graphify update . && neuralmind build . again.

Requirements

Requirement Version
Python 3.10 or higher
NeuralMind pip install neuralmind (includes the MCP server)
graphify pip install graphifyy

Supported OS: Linux, macOS, Windows 10+

Next Steps

Clone this wiki locally