Metadata-Version: 2.4
Name: vibe-me
Version: 0.1.0
Summary: Local RAG system with MCP server
Author: vibe_me contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/BorisFaj/vibe_me
Project-URL: Repository, https://github.com/BorisFaj/vibe_me
Project-URL: Issues, https://github.com/BorisFaj/vibe_me/issues
Keywords: rag,mcp,local-first,semantic-search,code-search
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qdrant-client
Requires-Dist: fastembed
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: pydantic
Requires-Dist: python-dotenv
Requires-Dist: mcp
Requires-Dist: watchdog
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/logo.png" alt="vibe_me logo" width="240" />
</p>

<h1 align="center">vibe_me</h1>

<p align="center">
  Local-first RAG + MCP server for codebases, documentation folders and project context.
</p>

<p align="center">
  Semantic search · Literal grep · Multi-project context · MCP tools · Incremental watcher
</p>

---

## 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:

```bash
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:

```bash
pip install vibe-me
```

### Using pyenv

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

```bash
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:

```bash
which vibe-me
which vibe-me-mcp
```

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

```bash
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:

```bash
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:

```text
~/.local/share/vibe-me
```

### Install From GitHub

For the latest unreleased version:

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

### Development Install

For contributing to `vibe_me` itself:

```bash
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:

```bash
vibe-me index .
```

Run semantic search:

```bash
vibe-me search "where is authentication configured"
```

Run exact literal search:

```bash
vibe-me grep "class User"
```

Show index status:

```bash
vibe-me status
```

Keep an index fresh while you work:

```bash
vibe-me watch .
```

## CLI Commands

```bash
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:

```bash
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:

```bash
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:

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

Replace an existing managed section with the latest template:

```bash
vibe-me update-agents --force
```

Preview without writing:

```bash
vibe-me update-agents --dry-run
```

## Manage Indexed Projects

List indexed projects:

```bash
vibe-me projects
vibe-me projects --json
```

Rename a project display name without changing its `project_id`:

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

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

```bash
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:

```bash
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:

```text
~/.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:

```text
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:

```bash
vibe-me mcp-stats
vibe-me mcp-stats --json
```

Show recent calls:

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

Clear local usage analytics:

```bash
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:

```text
~/.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:

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

Or override individual paths:

```bash
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:

```bash
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:

```text
~/.config/opencode/opencode.json
```

Minimal OpenCode MCP config:

```json
{
  "$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:

```bash
which vibe-me-mcp
```

Example with an explicit pyenv-style path:

```json
{
  "$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:

```bash
vibe-me index .
```

or keep a project fresh from a separate terminal with:

```bash
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:

```bash
export VIBE_DEFAULT_PROJECT="$PWD"
opencode
```

Optional launcher:

```bash
#!/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.

```text
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:

```bash
pip install -e ".[dev]"
```

Run checks:

```bash
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
