vibe-me 0.1.1

Local RAG system with MCP server

vibe_me

Local-first RAG + MCP server for codebases, documentation folders and project context.

Semantic search · Literal grep · Multi-project context · MCP tools · Incremental watcher

---

What It Is

vibe_me indexes local code and documentation, stores embeddings locally, and exposes search/read tools through an MCP server for coding agents such as OpenCode or any MCP-compatible client.

It is designed so each user runs it locally with their own projects, local index, and configuration.

Features

• Local semantic search over code and docs.
• Literal grep for exact symbols, config keys and errors.
• Multi-project search for combining app repos with local docs.
• SQLite metadata plus local Qdrant vector storage.
• Stable per-project isolation by absolute project path.
• MCP server exposing tools to coding agents.
• Optional incremental watcher to keep indexes fresh.

Requirements

• Python 3.11 or newer.
• Enough disk space for local embeddings and Qdrant data.
• Internet access on first use to download the default embedding model.
• Semantic search uses fastembed; PyTorch/CUDA is not required.

Install

Recommended for daily use:

pipx install vibe-me

This installs the vibe-me and vibe-me-mcp commands in an isolated environment and makes them available from any project.

If you prefer plain pip, install it into a Python environment that is available wherever your MCP client runs:

pip install vibe-me

Using pyenv

If you use pyenv, install vibe-me into a shared pyenv Python version, not inside each project virtualenv:

pyenv install 3.12
pyenv shell 3.12
python -m pip install --upgrade pip
python -m pip install vibe-me

Then make sure the pyenv shims are available in your shell:

which vibe-me
which vibe-me-mcp

If both commands resolve, you can use them from any project directory:

cd /path/to/any/project
vibe-me index .
vibe-me search "query"

For MCP clients such as OpenCode, the important part is that the client can find vibe-me-mcp. If command: ["vibe-me-mcp"] does not work, use the absolute path returned by:

which vibe-me-mcp

New virtualenvs created from that Python do not normally inherit globally installed packages. That is OK for vibe-me: you do not need to install it inside every project virtualenv. Install it once in a shared tooling Python and call the installed commands from your shell or MCP config.

Indexed data is shared across environments because it is stored outside virtualenvs by default:

~/.local/share/vibe-me

Install From GitHub

For the latest unreleased version:

pip install git+https://github.com/BorisFaj/vibe_me.git

Development Install

For contributing to vibe_me itself:

git clone https://github.com/BorisFaj/vibe_me.git
cd vibe_me
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Quick Start

Index the current project:

vibe-me index .

Run semantic search:

vibe-me search "where is authentication configured"

Run exact literal search:

vibe-me grep "class User"

Show index status:

vibe-me status

Keep an index fresh while you work:

vibe-me watch .

CLI Commands

vibe-me --help
vibe-me index .
vibe-me search "query" --project /path/to/project
vibe-me grep "literal text" --project /path/to/project
vibe-me search-many "query" -p /path/to/project -p /path/to/docs
vibe-me grep-many "literal text" -p /path/to/project -p /path/to/docs
vibe-me projects
vibe-me projects --json
vibe-me update-agents
vibe-me update-agents --target claude
vibe-me update-agents --target gemini
vibe-me mcp-stats
vibe-me mcp-log
vibe-me rename-project --project /path/to/project --name docs
vibe-me remove-project --project /path/to/project
vibe-me status --all
vibe-me watch .

Agent Instructions

Add a managed vibe-me MCP usage section to an agent instruction file:

vibe-me update-agents

By default this updates AGENTS.md in the current directory. It creates the file if needed and does not duplicate the section if it already exists.

Supported presets:

vibe-me update-agents --target agents
vibe-me update-agents --target claude
vibe-me update-agents --target gemini

These map to:

Target	File
agents	AGENTS.md
claude	CLAUDE.md
gemini	GEMINI.md

Use a custom file with:

vibe-me update-agents --file .github/copilot-instructions.md

Replace an existing managed section with the latest template:

vibe-me update-agents --force

Preview without writing:

vibe-me update-agents --dry-run

Manage Indexed Projects

List indexed projects:

vibe-me projects
vibe-me projects --json

Rename a project display name without changing its project_id:

vibe-me rename-project --project /path/to/project --name docs

If the current name is unique, you can also rename by name:

vibe-me rename-project --project-name old-name --name new-name

Renaming updates both SQLite metadata and Qdrant payloads, so future search results use the new name immediately.

Remove a project from the local index:

vibe-me remove-project --project /path/to/project

This removes SQLite metadata and Qdrant vectors for that project. It does not delete files from disk. Use --yes to skip the confirmation prompt.

MCP Usage Analytics

vibe_me records local MCP usage metadata in:

~/.local/share/vibe-me/usage.sqlite

It tracks tool calls, durations, result counts and estimated context savings. The estimate compares the context returned by vibe-me with an approximate baseline of reading the full files that search/grep/read results came from.

Token counts are estimates:

tokens ~= characters / 4

vibe_me cannot know the exact final LLM prompt or provider-side token usage, so these numbers should be read as local context-efficiency estimates, not billing-accurate token counts.

Show summary stats:

vibe-me mcp-stats
vibe-me mcp-stats --json

Show recent calls:

vibe-me mcp-log
vibe-me mcp-log --limit 50
vibe-me mcp-log --json

Clear local usage analytics:

vibe-me mcp-clear-stats

By default, usage analytics stores metadata and counts, not full returned file contents.

Local Data

By default, vibe_me stores its local index in:

~/.local/share/vibe-me

That directory contains SQLite metadata and local Qdrant vector storage. It is user-local data and should not be committed to your projects.

Override it with:

export VIBE_DATA_DIR=/path/to/vibe-me-data

Or override individual paths:

export VIBE_QDRANT_PATH=/path/to/qdrant
export VIBE_SQLITE_PATH=/path/to/index.sqlite

Configuration

Supported environment variables:

Variable	Default	Purpose
VIBE_DATA_DIR	~/.local/share/vibe-me	Base local storage directory
VIBE_QDRANT_PATH	$VIBE_DATA_DIR/qdrant	Local Qdrant storage path
VIBE_SQLITE_PATH	$VIBE_DATA_DIR/index.sqlite	SQLite metadata path
VIBE_COLLECTION_NAME	vibe_code	Qdrant collection name
VIBE_EMBEDDING_MODEL	BAAI/bge-small-en-v1.5	FastEmbed model
VIBE_DEFAULT_PROJECT	current working directory	Default MCP project
VIBE_AUTO_WATCH	0	Start watcher automatically with MCP server

See .env.example for a copyable template.

Default indexing excludes common dependency, build, cache and report folders such as .git, node_modules, .next, .vercel, coverage, playwright-report, dist and build. It also excludes large lock/report files such as package-lock.json, pnpm-lock.yaml, yarn.lock, coverage.xml and lcov.info.

MCP Server

Start the MCP server manually:

vibe-me-mcp

The server runs over stdio. Normally your MCP-compatible client starts it automatically.

The MCP server exposes tools for:

• search_codebase
• grep_codebase
• read_file
• refresh_index
• index_status
• search_many_codebases
• grep_many_codebases
• list_projects
• remove_project
• rename_project
• usage_stats
• default_project
• ping

OpenCode Setup

Use examples/opencode.json as a template for your user config, commonly:

~/.config/opencode/opencode.json

Minimal OpenCode MCP config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vibe-me": {
      "type": "local",
      "command": ["vibe-me-mcp"],
      "enabled": true,
      "environment": {
        "VIBE_AUTO_WATCH": "0"
      }
    }
  },
  "permission": {
    "tool": {
      "vibe-me_*": "allow"
    }
  }
}

This works when vibe-me-mcp is in the PATH visible to OpenCode. If you installed it into a shared pyenv Python and OpenCode cannot find it, use the absolute path returned by:

which vibe-me-mcp

Example with an explicit pyenv-style path:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vibe-me": {
      "type": "local",
      "command": [
        "/path/to/pyenv/versions/3.12.3/bin/vibe-me-mcp"
      ],
      "enabled": true,
      "environment": {
        "VIBE_AUTO_WATCH": "0"
      }
    }
  },
  "permission": {
    "tool": {
      "vibe-me_*": "allow"
    }
  }
}

VIBE_AUTO_WATCH=0 is the safest default: the MCP server will not start indexing automatically when your client opens. Run indexing explicitly with:

vibe-me index .

or keep a project fresh from a separate terminal with:

vibe-me watch .

Use VIBE_AUTO_WATCH=1 if you want the MCP server to start a background watcher automatically for the default project.

Do not put shell placeholders such as ${cwd} or $PWD directly in opencode.json; OpenCode passes environment values literally. If your client does not launch MCP servers from the project directory, set a default project before launching it:

export VIBE_DEFAULT_PROJECT="$PWD"
opencode

Optional launcher:

#!/usr/bin/env bash
set -euo pipefail

export VIBE_DEFAULT_PROJECT="$PWD"
exec opencode "$@"

Project Identity

Each indexed folder is treated as a separate project.

project_id   = absolute resolved project path
project_name = folder name unless overridden

Critical operations filter by project_id, so projects with similar names remain isolated.

Development

Install development dependencies:

pip install -e ".[dev]"

Run checks:

ruff check .
mypy rag mcp_server
pytest
python -m build
python -m twine check dist/*

Security Notes

vibe_me stores indexed chunks locally. If you index files containing secrets, those contents may be present in your local SQLite/Qdrant data. Keep your data directory private and do not commit it.

License

MIT