Get started with Vinemap

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/rohit0x62/vinemap/main/installers/install.sh | bash
# or
pip install vinemap

Windows (PowerShell)

irm https://raw.githubusercontent.com/rohit0x62/vinemap/main/installers/install.ps1 | iex
# or
pip install vinemap

Optional extras: pip install vinemap[treesitter] (precise parsers for 12 languages), vinemap[embeddings] (semantic ranking signal), vinemap[watch] (file watcher on save).

Quick start

cd your-project
vinemap .                    # interactive agent picker
vinemap quickstart .         # guided wizard: index + connect + sample query
vinemap index .              # build graph → .vinemap/
vinemap query "auth flow"    # ranked files
vinemap pack "auth flow" --budget 6000
vinemap watch .              # keep graph fresh on save (optional)
vinemap mcp .                # stdio MCP server

Per-agent setup

Each command indexes if needed, then writes agent-specific rules/hooks plus MCP config for pre-injection:

MCP-only wiring (no hooks): vinemap connect cursor|claude|gemini|codex|copilot|opencode

CLI reference

MCP tools

• graph_retrieve — ranked context pack for a query
• graph_read — symbols, imports, call edges for one file
• graph_neighbors — traverse import/call graph
• graph_stats — index statistics
• graph_diagnose, graph_health, graph_audit — diagnosis, health, and audit tools

Guardrails nudge agents away from blind grep/read loops with per-turn read budgets and duplicate-read hints.

Teams (self-hosted)

Teams requires a Teams license and a running graph server (Docker). See teams/README.md in the repo.

cd teams && docker compose up -d
vinemap teams connect http://localhost:7430 --token <token> .
vinemap teams push .
vinemap teams retrieve "where do we validate JWTs"
vinemap teams decisions --text "Auth validates JWT in gateway"
vinemap teams sync .
vinemap teams status .

Cross-repo retrieval, shared WHY memory with attribution, OIDC SSO, audit log, and seat management.

Troubleshooting

macOS

• If vinemap not found after install, restart the shell or add ~/.local/bin to PATH.
• Claude hooks need executable scripts — re-run vinemap claude ..

Linux

• Use python3 -m pip install vinemap if pip points to Python 2.
• For file watcher: pip install vinemap[watch] (watchdog).

Windows

• Run PowerShell as your user (not Admin) for the install script.
• Paths in the graph use forward slashes internally; index from the project root with vinemap index .
• MCP config for Cursor/VS Code lives under .cursor or .vscode in the project folder.

Common issues

• No index — run vinemap index . first.
• Large repos — use vinemap store migrate for SQLite backend, or raise --max-files on index.
• Stale graph — vinemap watch . or re-index after large refactors.
• Tree-sitter not active — install pip install vinemap[treesitter] and re-index.