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_codebasegrep_codebaseread_filerefresh_indexindex_statussearch_many_codebasesgrep_many_codebaseslist_projectsremove_projectrename_projectusage_statsdefault_projectping
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
Metadata
Release files for vibe-me 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vibe_me-0.1.1.tar.gz | 33.6 kB | With provenance | Details for vibe_me-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vibe_me-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for vibe_me-0.1.1-py3-none-any.whl |
Total release size: 62.2 kB
Release files / vibe_me-0.1.1.tar.gz
| Download URL | vibe_me-0.1.1.tar.gz |
|---|---|
| Size | 33.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9365a74fc372b7fa0c699d2614ae948ebc6bd71646bbddbe7d227b90b5b10e0a
|
|
BLAKE2b-256 checksum How to use checksums |
d99a113813c962961b93cc0e5bc10d02141243438fd2c7e7b7536131706cd7ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 28, 2026.
Transparency logRelease files / vibe_me-0.1.1-py3-none-any.whl
| Download URL | vibe_me-0.1.1-py3-none-any.whl |
|---|---|
| Size | 28.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7e69fcc032b1408efb7f16f0f2560da51d651586ce470459158c141bdc49f04d
|
|
BLAKE2b-256 checksum How to use checksums |
7392ad7351021a51fa35e63238188fd2dc38016693a34708a585c5d44bbf15ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 28, 2026.
Transparency logSecurity for vibe-me 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for vibe_me-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 28, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.