Skip to main content

​
Quickstart

Get OpenGround up and running in 5 minutes. This guide will take you from installation to your first documentation search.

​
Prerequisites

  • Python 3.10, 3.11, or 3.12
  • pip or uv package manager

​
Step 1: Install OpenGround

Install OpenGround using your preferred package manager: 
uv tool install openground
The default package includes sentence-transformers with automatic GPU/MPS/CPU support. For a lighter install, see Installation Options.

​
Step 2: Add Documentation

Let’s add the FastAPI documentation as an example: 
openground add fastapi \
  --source https://github.com/tiangolo/fastapi.git \
  --docs-path docs/ \
  --version 0.115.5 \
  -y
This command:
  • Clones the FastAPI repository at version 0.115.5
  • Extracts documentation from the docs/ folder
  • Chunks the text into manageable pieces
  • Generates embeddings using a local model
  • Stores everything in a local LanceDB database
The first time you add documentation, OpenGround will download the embedding model (~200MB for BGE-small-en-v1.5). This only happens once.
Expected output: 
Extraction complete: 150 pages extracted to ~/.openground/raw_data/fastapi/0.115.5
Chunking documents: 100%|████████████████████| 150/150 [00:02<00:00]
Generating embeddings: 100%|█████████████████| 800/800 [00:15<00:00]
Inserting 800 chunks into LanceDB...
Embedding complete: Library fastapi (0.115.5) added to LanceDB.

​
Step 3: Search Documentation

Now you can search the documentation: 
openground query "How do I create a route with path parameters?" \
  --library fastapi \
  --version 0.115.5
Example output: 
Found 10 matches.
1. **Path Parameters**: "You can declare path parameters in your path operation function parameters..."
   (Source: https://fastapi.tiangolo.com/tutorial/path-params/, Version: 0.115.5)
   
2. **Path Parameters with Types**: "You can declare the type of a path parameter in the function..."
   (Source: https://fastapi.tiangolo.com/tutorial/path-params/#path-parameters-with-types, Version: 0.115.5)
OpenGround uses hybrid search that combines semantic understanding with keyword matching for the best results.

​
Step 4: List Your Libraries

View all documentation you’ve added: 
openground list
Output: 
Available Libraries
┌──────────┬───────────┐
│ Library  │ Versions  │
├──────────┼───────────┤
│ fastapi  │ 0.115.5   │
└──────────┴───────────┘

​
Step 5: Connect to Your AI Agent

OpenGround really shines when connected to AI coding assistants. Install the MCP server: 
openground install-mcp --claude-code
Restart Claude Code and you’re ready! Your AI assistant can now search FastAPI documentation automatically.

​
What’s Next?

You now have OpenGround installed and working! Here are some next steps:

Add More Sources

Add documentation from git repos, sitemaps, or local files

Configure Settings

Customize chunk size, embedding models, and more

MCP Integration

Deep dive into AI agent integration

Advanced Search

Learn about hybrid search and tuning

​
Common Use Cases

openground add numpy \
  --source https://numpy.org/doc/stable/sitemap.xml \
  --filter-keyword reference \
  -y
This extracts all pages containing “reference” in the URL from NumPy’s documentation.
openground add my-project \
  --source ~/projects/my-project/docs \
  -y
Indexes documentation from your local project. Great for internal or private docs.
openground query "async database queries" --top-k 20
Omit the --library flag to search across all installed documentation.
openground update fastapi --version 0.115.6
OpenGround intelligently updates only what changed using content hashes.

​
Example: Complete Workflow

Here’s a complete workflow for a Python developer:
1

Install OpenGround

uv tool install openground
2

Add Python Framework Documentation

# FastAPI
openground add fastapi \
  --source https://github.com/tiangolo/fastapi.git \
  --docs-path docs/ \
  --version 0.115.5 \
  -y

# Pydantic
openground add pydantic \
  --source https://github.com/pydantic/pydantic.git \
  --docs-path docs/ \
  --version v2.9.0 \
  -y

# SQLAlchemy
openground add sqlalchemy \
  --source https://docs.sqlalchemy.org/sitemap.xml \
  --filter-keyword /en/20/ \
  -y
3

Install MCP for Claude Code

openground install-mcp --claude-code
4

Use in Your AI Assistant

In Claude Code, ask:
“How do I create a Pydantic model with validation?”
Claude will automatically search your local Pydantic documentation and provide accurate answers with sources.

​
Troubleshooting

The package isn’t in your PATH.Solution:
  • If using uv: Run uv tool update-shell and restart your terminal
  • If using pip: Ensure pip’s bin directory is in your PATH
  • Try running with full path: python -m openground
First extraction downloads the embedding model and clones repositories.This is normal:
  • Embedding model download: ~200MB, happens once
  • Git clone: depends on repo size
  • Subsequent additions are faster
To speed up:
  • Use --docs-path to extract only specific folders
  • Use faster internet connection for initial setup
  • Consider fastembed backend for faster CPU embeddings
Check that the library was added successfully.Solution:
# List libraries
openground list

# If missing, add it
openground add library-name --source <url> -y

# Check the version matches
openground query "your query" --library library-name --version <version>

​
Next Steps

Now that you have the basics, explore:
Need help? Check the troubleshooting guides or open an issue on GitHub.