Content
<!-- markdownlint-disable MD033 -->
# Documango
Documango is a terminal-first documentation browser for Go, Rust, AT Protocol, GitHub, and other ecosystems.
It ingests source materials into a single SQLite database (`.usde`) with compressed Markdown, full-text search, and agent-friendly metadata.
## Requirements
- Go 1.24+ (module declares go 1.24.5)
- `rg` (ripgrep) optional for section extraction; falls back to `grep`
- Git for AT Protocol ingestion
## Quick Start
Install & build the CLI:
```sh
go mod tidy
task build
```
Initialize a database:
```sh
./tmp/documango init -d ./tmp/docs.usde
```
Ingest AT Protocol documentation:
```sh
./tmp/documango add atproto -d ./tmp/docs.usde
```
Ingest a Hex package (Elixir/Gleam):
```sh
./tmp/documango add hex gleam_stdlib -d ./tmp/docs.usde
```
Ingest GitHub repository documentation:
```sh
./tmp/documango add github folke/snacks.nvim -d ./tmp/docs.usde
```
Search (namespace-aware):
```sh
./tmp/documango search "rust/serde/Serialize"
./tmp/documango search "atproto/lexicon/app.bsky.feed.post"
./tmp/documango search -p "go/net" "Client"
```
Read a document (raw markdown):
```sh
./tmp/documango read -d ./tmp/docs.usde atproto/lexicon/com.atproto.repo.createRecord
```
Read a document (rendered with Glamour):
```sh
./tmp/documango read -d ./tmp/docs.usde -r -w 80 atproto/lexicon/com.atproto.repo.createRecord
```
Extract a section by heading:
```sh
./tmp/documango read section -d ./tmp/docs.usde -q "Definition" -r atproto/lexicon/com.atproto.repo.createRecord
```
## Usage
### Configuration
Documango uses XDG Base Directory paths with `DOCUMANGO_HOME` override support:
- **macOS**: `~/Library/Application Support/documango/`
- **Linux**: `~/.local/share/documango/` (data), `~/.config/documango/` (config), `~/.cache/documango/` (cache)
Configuration is stored in TOML format:
```sh
./tmp/documango config show
./tmp/documango config set display.render_markdown true
./tmp/documango config edit
```
### Commands
<details>
<summary>Database</summary>
- `documango init [database-name]`: create a new `.usde` database
- `documango init -p /path/to/db.usde`: create at explicit path
</details>
<details>
<summary>Add (Ingest)</summary>
- `documango add go <module>`: ingest Go module from proxy.golang.org
- `documango add go --stdlib [-s <start>] [-m <max>]`: ingest Go stdlib packages
- `documango add atproto`: ingest AT Protocol lexicons, specs, and docs
- `documango add hex <package>`: ingest Elixir or Gleam package from Hex.pm
- `documango add rust <crate>`: ingest Rust crate from crates.io
- `documango add github <owner/repo>`: ingest Markdown documentation from GitHub repository
</details>
<details>
<summary>Search</summary>
- `documango search [-l N] [-t TYPE] [-f FORMAT] [-p PREFIX] <query>`
- **Namespace Aware**: Queries starting with `rust/`, `go/`, `atproto/`, `hex/`, or `github/` automatically filter by that namespace.
- **Path Qualified**: Searching for `rust/serde/Serialize` automatically treats `rust/serde/` as a package prefix and `Serialize` as the symbol query.
- **FTS5 Optimized**: Handles special characters (`/`, `::`, `-`) automatically by quoting terms to prevent SQL syntax errors.
- Formats: `table` (default), `json`, `paths`
- Types: `Func`, `Type`, `Package`, `Lexicon`, etc.
</details>
<details>
<summary>Read</summary>
- `documango read [-r] [-w N] [-s SECTION] <path>`: read full document
- `documango read section -q <heading> [-r] [-w N] <path>`: extract section by heading
- Flags: `--rg` (force ripgrep), `--gr` (force grep)
</details>
<details>
<summary>List & Info</summary>
- `documango list [--type PREFIX] [--tree] [--count]`: list all documentation paths
- `documango info <path>`: show document metadata
</details>
<details>
<summary>Cache</summary>
- `documango cache status`: show cache size and entry count
- `documango cache list [PREFIX]`: list cached items
- `documango cache prune [--age N]`: remove entries older than N days
- `documango cache clear [--type TYPE]`: clear cache
</details>
<details>
<summary>Config</summary>
- `documango config show`: display current configuration
- `documango config get <key>`: get configuration value
- `documango config set <key> <value>`: set configuration value
- `documango config edit`: open in $EDITOR
- `documango config path`: print config file path
- `-q, --quiet`: suppress non-error output
- `--no-color`: disable colored output
</details>
<details>
<summary>Global Flags</summary>
- `-d, --database PATH`: database path (default: XDG data directory)
- `-v, --verbose`: enable verbose output
- `-q, --quiet`: suppress non-error output
- `--no-color`: disable colored output
</details>
<details>
<summary>MCP (Model Context Protocol)</summary>
- `documango mcp serve [--stdio] [--http ADDR]`: start the MCP server
- `--stdio`: use standard input/output (for Claude Desktop, etc.)
- `--http`: use streamable HTTP transport on the given address
- `-d, --database PATH`: specify the database to serve
</details>
## Model Context Protocol (MCP)
Documango exposes its documentation through the [Model Context Protocol](https://modelcontextprotocol.io), allowing AI agents to search and read documentation programmatically.
### Tools
1. `search_docs(query, package)`: Search for documentation symbols or guides.
2. `read_doc(path)`: Retrieve the full decompressed Markdown content of a document.
3. `get_symbol_context(symbol)`: Retrieve a minimal token signature and summary for a symbol.
### Integration
To use with Claude Desktop or Antigravity, add the following to your configuration:
```json
{
"mcpServers": {
"documango": {
"command": "/path/to/documango",
"args": ["mcp", "serve", "--stdio"]
}
}
}
```
## Data Layer
### Ingesters
<details>
<summary>Go</summary>
Documango uses a single Go ingestion pipeline for both:
- Go modules via `proxy.golang.org`
- Go standard library via `pkg.go.dev` (directory list) + `go.googlesource.com` (archive fetch)
**Caching**: Module zips and stdlib tarballs are cached indefinitely in `~/.cache/documango/` to avoid re-fetching.
The standard library is stored in the Go namespace with paths like:
- `go/net/http`
- `go/crypto/tls`
Go ingestion extracts:
- Markdown docs via `gomarkdoc`
- FTS5 search entries (name, type, body)
- Agent context (signatures + synopsis)
</details>
<details>
<summary>AT Protocol</summary>
Ingests three documentation sources from Bluesky's GitHub repositories:
- **Lexicons**: JSON schemas converted to Markdown (`atproto/lexicon/*`)
- **Protocol Specs**: Technical specifications from atproto-website (`atproto/spec/*`)
- **Developer Docs**: Tutorials and guides from bsky-docs (`atproto/docs/*`)
</details>
<details>
<summary>Hex.pm (BEAM)</summary>
Ingests documentation for BEAM (Elixir, Erlang, and Gleam) packages directly from Hex.pm.
- **Gleam**: Parses `package-interface.json` to extract full type signatures, function signatures with labeled parameters, type definitions with constructors, and documentation strings. Generates comprehensive Markdown with Gleam syntax code blocks.
- **Elixir/Erlang**: Extracts documentation and metadata from ExDoc's `search_data-*.js`.
**Caching**: Documentation tarballs are cached in `~/.cache/documango/hex/packages/`.
The packages are stored in the hex namespace with paths like:
- `hex/phoenix/Phoenix.Controller`
- `hex/gleam_stdlib/gleam/list`
</details>
<details>
<summary>GitHub</summary>
Ingests Markdown documentation from GitHub repositories. Automatically discovers and processes all Markdown files including README, docs/ folders, and nested documentation.
- **API mode**: For smaller repositories, fetches content via the GitHub Git Trees API and raw file URLs
- **Clone mode**: Falls back to `git clone` for large repositories when the tree API returns truncated results
- **Front matter**: Extracts title from YAML front matter (e.g., `title: My Doc`) or falls back to the first H1 heading
- **Rate limiting**: Respects GitHub API rate limits with automatic retry and wait behavior
**Caching**: Cloned repositories are cached in `~/.cache/documango/github/repos/` for reuse across ingestions.
Documents are stored in the github namespace with paths like:
- `github/folke/snacks.nvim/README.md`
- `github/folke/snacks.nvim/docs/dashboard.md`
- `github/changesets/changesets/docs/intro.md`
</details>
### Model
Documentation is stored in a single SQLite database, called Unified Semantic Documentation Engine (`.usde`).
<details>
<summary>SQLite Schema</summary>
Documango stores all documentation in a single SQLite database (`.usde`). The design is intentionally simple and optimized for fast local search and cheap retrieval:
- `documents` holds compressed Markdown blobs, keyed by a virtual path (e.g., `go/net/http`)
- `search_index` is an FTS5 virtual table (trigram tokenizer) that supports fast substring search and ranking
- `agent_context` stores low‑token summaries and signatures for fast AI retrieval without decompressing full docs
```mermaid
erDiagram
documents ||--o{ search_index : "doc_id"
documents ||--o{ agent_context : "doc_id"
documents {
INTEGER id PK
TEXT path
TEXT format
BLOB body
BLOB raw_html
TEXT hash
}
search_index {
TEXT name
TEXT type
TEXT body
INTEGER doc_id FK
}
agent_context {
INTEGER doc_id FK
TEXT symbol
TEXT signature
TEXT summary
}
```
Search scoring details:
- Exact match bonus: +100 if the symbol name exactly matches the query
- BM25 score: Subtracted from the bonus (BM25 returns lower values for better matches)
- Result: Higher scores = more relevant
</details>
## Notes
- Stdlib ingestion can be rate-limited by upstream. Use `-s`/`-m` to ingest in batches.
- The `read section` command searches headings and returns the section until the next same-or-higher heading level.
- Cache is stored in:
- `~/.cache/documango/` (Linux)
- `~/Library/Caches/documango/` (macOS)
- Default database is created in:
- `~/.local/share/documango/default.usde` (Linux)
- `~/Library/Application Support/documango/default.usde` (macOS)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
firecrawl
Firecrawl MCP Server enables web scraping, crawling, and content extraction.
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Sequential Thinking
A structured MCP server for dynamic problem-solving and reflective thinking.