Smahtiepants

smahtiepants: search current local documentation

Your training data has a cutoff; library/framework/language APIs change after it. Before answering from memory, search the local docs and ground your answer in them. smahtiepants keeps a recently-mirrored copy of DevDocs (hundreds of docsets) with fast semantic + keyword search. In this repository, always invoke it as uv run smahtiepants from the repo root; do not call smahtiepants directly. Skip only when the question is conceptual/version-independent or no relevant docset exists.

Workflow

1. See what documentation is available locally

uv run smahtiepants docs installed

This lists installed docsets with their canonical Slug (e.g. javascript, react, express, python~3.13, cpp, css, docker, git). The slug is what you pass to --slug. Match the user's library/language to a slug here.

If you suspect a docset exists but isn't installed, list everything available:

uv run smahtiepants docs available --offline   # fast, from local cache metadata
uv run smahtiepants docs available             # refresh the list from DevDocs (network)

2. Install or update docs if needed

uv run smahtiepants docs install react redux        # install one or more docsets
uv run smahtiepants docs update                     # update all installed docsets
uv run smahtiepants docs update python              # update one docset

Slugs accept common aliases (js, ts, py, python, nodejs, c++), which resolve to canonical docsets. Installing also builds the search index when embeddings are configured.

3. Search the docs

uv run smahtiepants search "useEffect cleanup" --slug react --limit 5
uv run smahtiepants search "request body parsing" --slug express
uv run smahtiepants search "structuredClone" --language javascript
uv run smahtiepants search "cfg target_arch target_os target triple" --slug rust

Useful flags:

• --slug <slug> — restrict to a docset (repeatable). Strongly prefer scoping by slug/language; it makes results far more relevant.
• --language <name> — filter by language-like docset (repeatable).
• --limit <n> — number of results (default 10, max 50).
• --format text|json|xml (or --json) — output format.

The default text output gives a ranked list with a query-aware excerpt, the matched page identity, and a read hint for each match. If the excerpt directly answers the question, use it; if it only identifies the right page or omits edge cases, follow the read hint before answering. Queries may be natural language or grep-like API terms; for code and language reference docs, include exact identifiers, attributes, flags, function names, and the surrounding concept words you expect to see.

4. Get more context when an excerpt isn't enough

The CLI excerpt is a snippet. To see the full matched chunk (not just the trimmed excerpt), request JSON — the text field contains the complete chunk:

uv run smahtiepants search "useEffect cleanup" --slug react --limit 3 --format json

For reading an entire documentation page, prefer the CLI command in the read hint:

uv run smahtiepants docs page <slug> <pageId>

Copy docsetSlug and pageId from the search result into this command. It reads the installed Markdown page directly from the local cache; do not start smahtiepants serve, call REST, or try MCP for a CLI workflow.

uv run smahtiepants docs page react hooks/useeffect

Use --start-line and --end-line for a bounded section of a large page, or --json when structured content and line metadata are useful. If a result looks close but the excerpt is ambiguous, read the full page before concluding the docs do not contain the answer.

5. Ground your answer

Base your answer on what the docs actually say. If local docs contradict your prior assumption, trust the docs and say what changed. Reference the docset and page so the user can verify (e.g. "per the local react docs page hooks/useeffect…"). If no relevant docset is installed, say so rather than guessing, and offer to install it.

Quick reference

See references/cli.md for the complete command surface and output details.