Alcove

Alcove ist ein MCP-Server, der KI-Coding-Agenten On-Demand-Zugriff auf deine privaten Projektdokumente gewährt – ohne alles in das Kontextfenster zu laden, ohne Dokumente in öffentliche Repositories zu leaken und ohne pro-Projekt-Konfiguration für jeden verwendeten Agenten.

Demo

Claude, Gemini, Codex — suchen · Projekte wechseln · globale Suche · validieren & generieren. Ein Setup.

alcove search · Projektwechsel · --scope global · alcove validate

Das Problem

Du hast zwei schlechte Optionen.

Option A: Dokumente in CLAUDE.md / AGENTS.md ablegen Jede Datei wird bei jedem Durchlauf in das Kontextfenster geladen. Funktioniert bei kurzen Konventionen. Versagt bei echten Projektdokumentationen. 10 Architekturdateien = Kontext-Überladung = langsamere, teurere, weniger präzise Antworten.

Option B: Dokumente nicht einbinden Dein Agent erfindet Anforderungen, die du bereits dokumentiert hast. Er ignoriert Einschränkungen aus Entscheidungen, die du bereits getroffen hast. Er bittet dich, bei jeder Sitzung dieselben Dinge zu erklären.

Keine der Optionen ist skalierbar. Multipliziere das nun mit 5 Projekten und 3 Agenten, die jeweils unterschiedlich konfiguriert sind. Jedes Mal, wenn du wechselst, verlierst du den Kontext.

Wie Alcove das löst

Alcove lädt deine Dokumente nicht in den Kontext. Agenten suchen nach dem, was sie brauchen, genau dann, wenn sie es brauchen.

~/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

Wechsle jederzeit den Agenten. Wechsle jederzeit das Projekt. Die Dokumentenebene bleibt standardisiert.

Die richtige Aufteilung

CLAUDE.md / AGENTS.md ist für das Verhalten des Agenten gedacht: wiederkehrende Fehler, die vermieden werden sollen, Coding-Konventionen und sitzungsspezifische Anweisungen. Halte dies unter 200 Zeilen.

Alcove ist für Projektwissen gedacht: Architektur, Entscheidungen, Runbooks, API-Dokumentationen und alles andere, was dein Agent verstehen muss – aber nicht unbedingt bei jedem Durchlauf.

Das Muster:

CLAUDE.md | AGENTS.md                             ← agent rules, coding conventions, recurring corrections
~/.config/alcove/docs/my-app/
  ARCHITECTURE.md                      ← tech stack, data model, system design
  DECISIONS.md                         ← why X was chosen over Y
  DEBT.md                              ← known issues, workarounds
  ...                                  ← agent searches here when it needs context

Agenten rufen search_project_docs("auth flow") auf und erhalten die 2 relevantesten Dokumente – nicht alle 12. Nichts landet im Kontextfenster, es sei denn, es wird tatsächlich benötigt.

Warum Alcove

Warum nicht einfach CLAUDE.md verwenden? Kurze Konventionen und Agentenverhalten gehören dorthin. Projektdokumentation – Architektur, Entscheidungen, Runbooks, PRDs – skaliert nicht in einer Kontextdatei. Alcove ist kein Ersatz; es ist die Ebene, die CLAUDE.md nie sein sollte.

Schnellstart

# 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

Hinweis: Vorgefertigte Binärdateien sind für Linux (x86_64), macOS (Apple Silicon & Intel) und Windows verfügbar.

setup führt dich interaktiv durch alles:

1. Wo deine Dokumente liegen

2. Welche Dokumentenkategorien verfolgt werden sollen

3. Bevorzugtes Diagrammformat

4. Welche KI-Agenten konfiguriert werden sollen (MCP + Skill-Dateien)

Führe alcove setup jederzeit erneut aus, um Einstellungen zu ändern. Es merkt sich deine vorherigen Entscheidungen.

Funktionsweise

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

Deine Dokumente sind in einem separaten Verzeichnis (DOCS_ROOT) organisiert, ein Ordner pro Projekt. Alcove verwaltet die Dokumente dort und stellt sie jedem MCP-kompatiblen KI-Agenten über stdio zur Verfügung. Dein Agent ruft Tools wie search_project_docs("auth flow") auf und erhält rangierte, projektspezifische Ergebnisse – unabhängig davon, welchen Agenten du verwendest.

Was es tut

• On-Demand-Dokumentenabruf – Agenten suchen und rufen ab; nichts wird vorab in den Kontext geladen

• BM25-rangierte Suche – schnelle Volltextsuche, unterstützt durch tantivy; relevanteste Dokumente zuerst, automatisch indiziert, Fallback auf grep

• Ein Dokumenten-Repo, mehrere Projekte – private Dokumente nach Projekt organisiert, an einem zentralen Ort verwaltet

• Ein Setup, jeder Agent – einmal konfigurieren, jeder MCP-kompatible Agent erhält denselben Zugriff

• Automatische Projekterkennung aus dem CWD – keine pro-Projekt-Konfiguration erforderlich

• Bereichsbeschränkter Zugriff – jedes Projekt sieht nur seine eigenen Dokumente

• Projektübergreifende Suche – Suche über alle Projekte gleichzeitig mit scope: "global"

• Private Dokumente bleiben privat – Dokumente berühren nie dein öffentliches Repo, läuft vollständig auf deinem Rechner über stdio

• Standardisierte Dokumentenstruktur – policy.toml erzwingt konsistente Dokumente über alle Projekte und Teams hinweg

• Repo-übergreifende Prüfung – findet interne Dokumente, die im Projekt-Repo falsch abgelegt wurden, und schlägt Korrekturen vor

• Dokumentenvalidierung – prüft auf fehlende Dateien, nicht ausgefüllte Vorlagen, erforderliche Abschnitte

• Funktioniert mit 9+ Agenten – 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

Suche

Alcove wählt automatisch die beste Suchstrategie. Wenn der Suchindex existiert, verwendet es die BM25-rangierte Suche (unterstützt durch tantivy) für relevanzbewertete Ergebnisse. Wenn nicht, greift es auf grep zurück. Du musst nie darüber nachdenken.

# 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

Der Index wird automatisch im Hintergrund erstellt, wenn der MCP-Server startet, und neu erstellt, wenn Dateiänderungen erkannt werden. Keine Cron-Jobs, keine manuellen Schritte.

Wie es für Agenten funktioniert: Agenten rufen einfach search_project_docs mit einer Abfrage auf. Alcove erledigt den Rest – Ranking, Deduplizierung (ein Ergebnis pro Datei), projektübergreifende Suche und Fallback. Der Agent muss nie einen Suchmodus wählen.

Globale Suche

Jede Architektur-Entscheidung, jedes Runbook, jede Projektnotiz – durchsuchbar über alle deine Projekte hinweg.

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

Agenten können dasselbe mit scope: "global" in search_project_docs tun. Eine Abfrage, jedes Projekt.

Projekterkennung

Standardmäßig erkennt Alcove das aktuelle Projekt anhand des Arbeitsverzeichnisses (CWD) deines Terminals. Du kannst dies mit der Umgebungsvariable MCP_PROJECT_NAME überschreiben:

MCP_PROJECT_NAME=my-api alcove

Dies ist nützlich, wenn dein CWD nicht mit einem Projektnamen in deinem Dokumenten-Repo übereinstimmt.

Dokumentenrichtlinie

Definiere teamweite Dokumentationsstandards mit policy.toml in deinem Dokumenten-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

Richtliniendateien werden mit Priorität aufgelöst: Projekt (<project>/.alcove/policy.toml) > Team (DOCS_ROOT/.alcove/policy.toml) > Eingebauter Standard (aus deinen config.toml Kerndateien). Dies stellt eine konsistente Dokumentenqualität über alle deine Projekte hinweg sicher und ermöglicht gleichzeitig pro-Projekt-Überschreibungen.

Dokumentenklassifizierung

Alcove klassifiziert Dokumente in Stufen:

Das audit-Tool scannt sowohl dein Dokumenten-Repo als auch das lokale Projektverzeichnis und schlägt dann Aktionen vor – wie das Generieren eines öffentlichen README aus deinem privaten PRD oder das Zurückholen falsch abgelegter Berichte in Alcove.

Konfiguration

Die Konfiguration liegt unter ~/.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 dies wird interaktiv über alcove setup eingestellt. Du kannst die Datei auch direkt bearbeiten.

Dateilisten sind vollständig anpassbar – füge jeden Dateinamen zu jeder Kategorie hinzu oder verschiebe Dateien zwischen Kategorien, um sie an den Workflow deines Teams anzupassen:

[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

Unterstützte Agenten

Agenten mit Skill-Unterstützung aktivieren Alcove automatisch, wenn du nach Projektarchitektur, Konventionen, Entscheidungen oder Status fragst. Sie können auch explizit aufgerufen werden:

/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

Unterstützte Sprachen

Die CLI erkennt automatisch deine System-Locale. Du kannst sie auch mit der Umgebungsvariable ALCOVE_LANG überschreiben.

# Override language
ALCOVE_LANG=ko alcove setup

Update

# Homebrew
brew upgrade epicsagas/alcove/alcove

# cargo-binstall
cargo binstall alcove

# From source
cargo install alcove

Deinstallation

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

Ökosystem

[obsidian