alcove

Your AI agent doesn't know your project. Alcove fixes that.

English · 한국어 · 日本語 · 简体中文 · Español · हिन्दी · Português · Deutsch · Français · Русский

Alcove is an MCP server that gives AI coding agents on-demand access to your private project docs — without dumping everything into the context window, without leaking docs into public repos, and without per-project config for every agent you use.

Demo

Claude, Gemini, Codex — search · switch projects · global search · validate & generate. One setup.

alcove search · project switch · --scope global · alcove validate

The problem

You have two bad options.

Option A: Put docs in CLAUDE.md / AGENTS.mdEvery file gets injected into the context window on every run.Works for short conventions. Breaks down with real project docs.10 architecture files = context bloat = slower, more expensive, less accurate responses.

Option B: Don't put docs inYour agent invents requirements you already documented.It ignores constraints from decisions you already made.It asks you to explain the same things every session.

Neither option scales. Now multiply it across 5 projects and 3 agents, each configured differently. Every time you switch, you lose context.

How Alcove solves this

Alcove doesn't inject your docs. Agents search for what they need, when they need it.

~/projects/my-app $ claude "how is auth implemented?"

  → Alcove detects project: my-app
  → BM25 search: "auth" → ARCHITECTURE.md (score: 0.94), DECISIONS.md (score: 0.71)
  → Agent gets the 2 most relevant docs, not all 12

~/projects/my-api $ codex "review the API design"

  → Alcove detects project: my-api
  → Same doc structure, same access pattern
  → Different project, zero reconfiguration

Switch agents anytime. Switch projects anytime. The document layer stays standardized.

Why Alcove

Why not just use CLAUDE.md? Short conventions and agent behaviors belong there. Project documentation — architecture, decisions, runbooks, PRDs — doesn't scale in a context file. Alcove is not a replacement; it's the layer CLAUDE.md was never meant to be.

Quick start

# macOS
brew install epicsagas/alcove/alcove

# Linux / Windows — pre-built binary (fast, no compilation)
cargo install cargo-binstall
cargo binstall alcove

# Any platform — build from source
cargo install alcove

# Clone and build
git clone https://github.com/epicsagas/alcove.git
cd alcove
make install

alcove setup

Note: Pre-built binaries are available for Linux (x86_64), macOS (Apple Silicon & Intel), and Windows.

setup walks you through everything interactively:

1. Where your docs live
2. Which document categories to track
3. Preferred diagram format
4. Which AI agents to configure (MCP + skill files)

Re-run alcove setup anytime to change settings. It remembers your previous choices.

How it works

flowchart LR
    subgraph Projects["Your projects"]
        A1["my-app/\n  src/ ..."]
        A2["my-api/\n  src/ ..."]
    end

    subgraph Docs["Your private docs (one repo)"]
        D1["my-app/\n  PRD.md\n  ARCH.md"]
        D2["my-api/\n  PRD.md\n  ..."]
        P1["policy.toml"]
    end

    subgraph Agents["Any MCP agent"]
        AG["Claude Code · Cursor\nGemini CLI · Codex · Copilot\n+4 more"]
    end

    subgraph MCP["Alcove MCP server"]
        T["search · get_file\noverview · audit\ninit · validate"]
    end

    A1 -- "CWD detected" --> D1
    A2 -- "CWD detected" --> D2
    Agents -- "stdio MCP" --> MCP
    MCP -- "scoped access" --> Docs

Your docs are organized in a separate directory (DOCS_ROOT), one folder per project. Alcove manages docs there and serves them to any MCP-compatible AI agent over stdio. Your agent calls tools like search_project_docs("auth flow") and gets ranked, project-specific results — regardless of which agent you're using.

What it does

• On-demand doc retrieval — agents search and retrieve; nothing is pre-loaded into context
• BM25 ranked search — fast full-text search powered by tantivy; most relevant docs first, auto-indexed, falls back to grep
• One doc-repo, multiple projects — private docs organized by project, managed in a single place
• One setup, any agent — configure once, every MCP-compatible agent gets the same access
• Auto-detects your project from CWD — no per-project config needed
• Scoped access — each project only sees its own docs
• Cross-project search — search across all projects at once with scope: "global"
• Private docs stay private — docs never touch your public repo, runs entirely on your machine over stdio
• Standardized doc structure — policy.toml enforces consistent docs across all projects and teams
• Cross-repo audit — finds internal docs misplaced in your project repo, suggests fixes
• Document validation — checks for missing files, unfilled templates, required sections
• Works with 9+ agents — Claude Code, Cursor, Claude Desktop, Cline, OpenCode, Codex, Copilot, Antigravity, Gemini CLI

MCP Tools

CLI

alcove              Start MCP server (agents call this)
alcove setup        Interactive setup — re-run anytime to reconfigure
alcove doctor       Check the health of your alcove installation
alcove validate     Validate docs against policy (--format json, --exit-code)
alcove index        Build or rebuild the full-text search index for ranked search
alcove search       Search docs from the terminal
alcove uninstall    Remove skills, config, and legacy files

Search

Alcove automatically picks the best search strategy. When the search index exists, it uses BM25 ranked search (powered by tantivy) for relevance-scored results. When it doesn't, it falls back to grep. You never have to think about it.

# Search the current project (auto-detected from CWD)
alcove search "authentication flow"

# Force grep mode if you want exact substring matching
alcove search "FR-023" --mode grep

The index builds automatically in the background when the MCP server starts, and rebuilds when it detects file changes. No cron jobs, no manual steps.

How it works for agents: agents just call search_project_docs with a query. Alcove handles the rest — ranking, deduplication (one result per file), cross-project search, and fallback. The agent never needs to choose a search mode.

Global search

Every architecture decision, every runbook, every project note — searchable across all your projects at once.

# Search across ALL projects
alcove search "rate limiting patterns" --scope global
alcove search "OAuth token refresh" --scope global

Agents can do the same with scope: "global" in search_project_docs. One query, every project.

Project detection

By default, Alcove detects the current project from your terminal's working directory (CWD). You can override this with the MCP_PROJECT_NAME environment variable:

MCP_PROJECT_NAME=my-api alcove

This is useful when your CWD doesn't match a project name in your docs repo.

Document policy

Define team-wide documentation standards with policy.toml in your docs repo:

[policy]
enforce = "strict"    # strict | warn

[[policy.required]]
name = "PRD.md"
aliases = ["prd.md", "product-requirements.md"]

[[policy.required]]
name = "ARCHITECTURE.md"

  [[policy.required.sections]]
  heading = "## Overview"
  required = true

  [[policy.required.sections]]
  heading = "## Components"
  required = true
  min_items = 2

Policy files are resolved with priority: project (<project>/.alcove/policy.toml) > team (DOCS_ROOT/.alcove/policy.toml) > built-in default (from your config.toml core files). This ensures consistent doc quality across all your projects while allowing per-project overrides.

Document classification

Alcove classifies docs into tiers:

The audit tool scans both your doc-repo and local project directory, then suggests actions — like generating a public README from your private PRD, or pulling misplaced reports back into Alcove.

Configuration

Config lives at ~/.config/alcove/config.toml:

docs_root = "/Users/you/documents"

[core]
files = ["PRD.md", "ARCHITECTURE.md", "PROGRESS.md", "DECISIONS.md", "CONVENTIONS.md", "SECRETS_MAP.md", "DEBT.md"]

[team]
files = ["ENV_SETUP.md", "ONBOARDING.md", "DEPLOYMENT.md", "TESTING.md", ...]

[public]
files = ["README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", ...]

[diagram]
format = "mermaid"

All of this is set interactively via alcove setup. You can also edit the file directly.

File lists are fully customizable — add any filename to any category, or move files between categories to match your team's workflow:

[core]
files = ["PRD.md", "ARCHITECTURE.md", "DECISIONS.md", "MY_SPEC.md"]  # added custom doc

[public]
files = ["README.md", "CHANGELOG.md", "PRD.md"]  # PRD exposed as public for this project

Supported agents

Agents with skill support activate Alcove automatically when you ask about project architecture, conventions, decisions, or status. They can also be invoked explicitly:

/alcove                          Summarize current project docs and status
/alcove search auth flow         Search docs for a specific topic
/alcove what conventions apply?  Ask a doc question directly

Supported languages

The CLI automatically detects your system locale. You can also override it with the ALCOVE_LANG environment variable.

# Override language
ALCOVE_LANG=ko alcove setup

Update

# Homebrew
brew upgrade epicsagas/alcove/alcove

# cargo-binstall
cargo binstall alcove

# From source
cargo install alcove

Uninstall

alcove uninstall          # remove skills & config
cargo uninstall alcove    # remove binary

Contributing

Bug reports, feature requests, and pull requests are welcome. Please open an issue on GitHub to start a discussion.

License

Apache-2.0