Alcove

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

→ Quick start

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

Alcove is an HTTP API server that gives AI coding agents on-demand access to your private project docs — BM25 + vector hybrid search for precision retrieval, tree-sitter code indexing so agents understand your codebase structure, and policy enforcement for doc consistency. No context bloat, no leaking docs into public repos, no per-project config for every agent.

Demo

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

CLI demo

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

The problem

Your AI agent starts every session from zero.

It doesn't know your architecture. It ignores constraints from decisions you already made. It asks you to explain the same things every session.

The context window is the bottleneck. Every token costs money and attention. Loading 10 architecture docs into context wastes 50K+ tokens on every run — and Anthropic's own docs warn that bloated config files make agents ignore your actual instructions.

So you have three bad options:

Stuff everything into agent config — every file loads into context on every run. 10 docs = context bloat = slower, more expensive, less accurate responses.

Copy-paste into every chat — works once, doesn't scale past one session.

Don't bother — your agent invents requirements you already documented, ignores constraints from decisions you already made, and you re-explain the same architecture every Monday morning.

Now multiply it across 5 projects and 3 agents. 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 "/alcove 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 "/alcove 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

Alcove gives your agents a memory that survives between sessions.

Agents don't load your docs into context. They search for what they need, when they need it. Architecture docs, design decisions, runbooks, constraints — all in one place, searchable, never in your public repo.

Agent config is for agent behavior. Alcove is for project knowledge.

Agent config files                ← agent rules, coding conventions, recurring corrections
~/.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

| Without a doc layer | With Alcove | |---------------------|-------------| | Docs in agent config bloat context on every run | Hybrid search (BM25 + RAG) — agents pull only what they need, ranked by relevance | | Agent only sees text docs, not code structure | Tree-sitter code indexing — agents understand modules, functions, and types across 12 languages | | Internal docs scattered across Notion, Google Docs, local files | One doc-repo, structured by project | | Each AI agent configured separately for doc access | One setup, all agents share the same access | | Switching projects means re-explaining context | CWD auto-detection, instant project switch | | Agent search returns random matching lines | Ranked results — best matches first, one result per file | | "Search all my notes about OAuth" — impossible | Global search across every project in one query | | Sensitive docs sitting in project repos | Private docs on your machine, never in public repos | | Doc structure differs per project and team member | policy.toml enforces standards across all projects | | No way to check if docs are complete | validate catches missing files, empty templates, missing sections | | Stale docs with broken links or WIP markers go unnoticed | lint detects broken links, orphans, and stale markers automatically | | Notes from Obsidian or other tools stay siloed | promote brings any note into your doc-repo with one command |

Quick start

> Required: Run alcove setup once after installation to configure your docs root and enable full functionality. Plugins start the API server automatically, but Alcove cannot search or index documents until setup has been run. > > Using Obsidian? See the [Ecosystem](#ecosystem) section for the docs structure and vault configuration.

Claude Code

/plugin marketplace add epicsagas/plugins
/plugin install alcove@epicsagas

Auto-installs the binary and starts the API server on next session start.

alcove setup   # run once after plugin install

Updates with claude plugin update alcove@epicsagas.

Codex CLI

codex plugin marketplace add epicsagas/plugins

Auto-installs the skill and starts the API server. Available immediately — no further steps needed.

Updates with codex plugin update alcove@epicsagas.

macOS (Apple Silicon only)

brew install epicsagas/tap/alcove

No Homebrew? Use the installer script:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/alcove/releases/latest/download/install.sh | sh

Linux (x86_64 / ARM64)

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/alcove/releases/latest/download/install.sh | sh

Windows (x86_64 / ARM64)

irm https://github.com/epicsagas/alcove/releases/latest/download/install.ps1 | iex

Antigravity (Gemini CLI)

agy plugins install https://github.com/epicsagas/alcove

Auto-installs the plugin (API server, skill, hooks) and starts it on next session start.

alcove setup   # run once after plugin install

Via Rust toolchain

cargo binstall alcove   # pre-built binary, includes hybrid search
cargo install alcove --features full-macos   # build from source (macOS)
cargo install alcove --features full-cross   # build from source (Linux/Windows)

> Note: cargo binstall downloads a pre-built binary with hybrid search (vector + BM25) included. When building from source, --features full-macos or --features full-cross is required for hybrid search support. Without features, only BM25 (keyword) search is available.

First-time setup (required)

After installing via any method above, run:

alcove setup
alcove --version
alcove doctor

setup walks you through everything interactively:

1. Where your docs live
2. Which document categories to track
3. Preferred diagram format
4. Embedding model for hybrid search
5. Background server — eliminate cold-start on every session (macOS login item)
6. Which AI agents to configure (skill files — Claude Code and Codex are handled by their plugin systems)

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

Optional dependencies

| Tool | Purpose | Install | |---|---|---| | pdftotext (poppler) | Full PDF text extraction — required for PDF search | macOS: brew install poppler · Debian/Ubuntu: apt install poppler-utils · Fedora: dnf install poppler-utils · Windows: poppler for Windows |

Without pdftotext, Alcove falls back to a built-in PDF parser which may fail on some files. Run alcove doctor to check your setup.

Troubleshooting

Agent can't find Alcove tools Run alcove setup again — it reconfigures the API server for all configured agents. Then start a new agent session (changes take effect on next session start).

Search returns no results The index may not be built yet. Run alcove index to build it, then try again.

403 Unauthorized from background server ALCOVE_TOKEN is not set in your shell. Run alcove token to print it, then add export ALCOVE_TOKEN="..." to your shell profile and reload.

alcove doctor reports issues Follow the suggestions printed by doctor — it checks binary location, API server status, index state, and optional dependencies like pdftotext.

Usage

CLI Search

Search through your documents directly from the terminal. By default, it searches across all projects (global scope).

# Basic search (global scope)
alcove search "authentication"

# Limit search to the current project (auto-detected via CWD)
alcove search "auth flow" --scope project

# Force grep mode (exact substring match)
alcove search "TODO" --mode grep

# Force ranked mode (BM25/Hybrid)
alcove search "data model" --mode ranked

# Adjust result limit
alcove search "deployment" --limit 5

Coding Agents (HTTP API)

AI coding agents use Alcove through a local HTTP API. The URL and auth token are resolved once per session with alcove api env:

eval $(alcove api env)
# sets ALCOVE_URL=http://127.0.0.1:
# sets ALCOVE_TOKEN=  (only if configured)

Agents can verify connectivity with the verify or rag status argument — it checks the daemon, resolves the URL, and calls /health automatically. You don't usually need to call these yourself; the agent will invoke them when you ask questions about your project.

| Endpoint | Method | Description | |----------|--------|-------------| | /health | GET | Health check — verify the API server is running | | /search?q=... | GET | Search documentation (query parameter) | | /v1/search | POST | Search with JSON body (supports scope, limit, mode) | | /projects | GET | List all projects in the doc-repo | | /projects | POST | Initialize a new project from templates | | /projects/{name}/docs | GET | List docs for a project with sizes and classification | | /projects/{name}/audit | GET | Audit doc health (missing, outdated, misplaced) | | /projects/{name}/validate | GET | Validate docs against policy.toml | | /projects/{name}/config | PUT | Update project settings in alcove.toml | | /docs/{path} | GET | Read a specific doc file (query: project, offset, limit) | | /index | POST | Update search index (incremental, all projects) | | /projects/{name}/index | POST | Update search index (single project) | | /changes | GET | Check changed files since last index (query: auto_rebuild) | | /lint | GET | Lint docs — broken links, orphans, stale markers (query: project) | | /vaults | GET | List all knowledge base vaults | | /vaults/search?q=... | GET | Search vaults (query: vault, limit) | | /vaults/backup | POST | Git snapshot of vault state | | /promote | POST | Import a file into the doc-repo | | /index-code | POST | Index source code via tree-sitter | | /mcp | POST | JSON-RPC proxy for all 16 MCP tools (legacy) |

> Note: MCP is still available — see registry/mcp.json for manual MCP setup if you prefer stdio-based access.

Example API calls:

# Health check
curl http://localhost:58301/health

# Search docs
curl "http://localhost:58301/search?q=authentication+flow"

# Advanced search with JSON body
curl -X POST http://localhost:58301/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "api endpoint", "scope": "global", "limit": 5}'

Example agent interaction: > User: "/alcove How do I add a new API endpoint?" > Agent: (calls POST /v1/search with query="add api endpoint") > Agent: (reads the most relevant doc via GET /docs/{path}?project=...) > Agent: "According to ARCHITECTURE.md, you need to..."

---

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 AI agent"]
        AG["Claude Code · Cursor\nCodex · Copilot\n+4 more"]
    end

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

    A1 -- "CWD detected" --> D1
    A2 -- "CWD detected" --> D2
    Agents -- "HTTP :58301" --> API
    API -- "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 AI agent over HTTP on port 58301.

API Endpoints

| Endpoint | Method | What it does | |----------|--------|-------------| | /health | GET | Health check — verify the API server is running | | /search?q=... | GET | Search documentation (query parameter) | | /v1/search | POST | Search with JSON body (scope, limit, mode) | | /projects | GET | List all projects | | /projects | POST | Initialize a new project | | /projects/{name}/docs | GET | List docs for a project | | /projects/{name}/audit | GET | Audit doc health | | /projects/{name}/validate | GET | Validate docs against policy | | /projects/{name}/config | PUT | Update project settings | | /docs/{path} | GET | Read a doc file | | /rebuild | POST | Rebuild search index | | /changes | GET | Check changed files | | /lint | GET | Lint docs | | /vaults | GET | List vaults | | /vaults/search?q=... | GET | Search vaults | | /vaults/backup | POST | Backup vault | | /promote | POST | Import file into doc-repo | | /index-code | POST | Index code structure | | /mcp | POST | JSON-RPC proxy (legacy MCP) |

> Note: MCP is still available for manual setup — see registry/mcp.json for stdio-based access.

CLI

alcove              Start API 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 lint         Semantic lint — broken links, orphans, stale markers (--format json)
alcove promote      Bring a file from an external vault into your doc-repo
alcove index        Update the search index (incremental — only changed files)
alcove rebuild      Rebuild the search index from scratch (use after schema changes)
alcove search       Search docs from the terminal
alcove bench        Search quality benchmark [--corpus] (precision, latency, regression detection)
alcove index-code   Generate code structure index from source [--language LANG] [--source PATH]
alcove token        Print the bearer token (for background server auth)
alcove uninstall    Remove skills, config, and legacy files

alcove mcp       Manage background API server lifecycle (start, stop, status, enable, disable)

alcove vault create   Create a new knowledge base vault
alcove vault link     Link an external directory as a vault (e.g., Obsidian)
alcove vault list     List all vaults with document counts
alcove vault remove   Remove a vault (symlinks: remove link only)
alcove vault add      Add a document to a vault
alcove vault index    Build search index for vaults
alcove vault rebuild  Rebuild vault search index from scratch

Code Indexing

Parse source files with tree-sitter and generate CODE_INDEX.md — a module-level markdown summary of your codebase that integrates with the Tantivy search pipeline.

# Index the current project's source (auto-detects all languages)
alcove index-code --source ./src

# Monorepo: index a directory with multiple languages at once
alcove index-code --source ./

# Restrict to a single language (useful when only one language

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [epicsagas](https://github.com/epicsagas)
- **Source:** [epicsagas/alcove](https://github.com/epicsagas/alcove)
- **License:** Apache-2.0
- **Homepage:** https://crates.io/crates/alcove

Install and usage instructions live in the source repository linked above.