pipx install docmancer --python python3.13

Quickstart

# 1. Install pipx
brew install pipx
pipx ensurepath

# 2. Open a new shell, then install docmancer
pipx install docmancer --python python3.13

# 3. Ingest a docs source
docmancer ingest https://docs.example.com

# 4. Install the skill into your agents
docmancer install claude-code
docmancer install cursor
docmancer install codex

# 5. Query from the CLI
docmancer query "How do I authenticate?"

No server to start. Config and the default vector store are created under ~/.docmancer/ on first use.

The Problem

Claude Code sessions have a context limit. Every time you paste docs into a session, or let the agent browse and re-fetch the same pages, you're burning that budget on setup instead of actual work. Once the session gets noisy enough, the agent starts guessing: made-up CLI flags, stale API shapes, behaviors from old versions.

The obvious fix (dumping whole doc sites into context) makes it worse. You burn thousands of tokens on irrelevant text and bury the one paragraph that actually matters.

Cloud-based doc tools add rate limits, privacy exposure, and server dependencies you don't need.

Docmancer solves this differently. You ingest docs once, they're chunked and indexed locally, and the agent retrieves only the matching sections when it needs them: a few hundred tokens instead of tens of thousands.

Works With Every Agent

Docmancer installs a skill file into each agent that teaches it to call the CLI directly. One local index, one ingest step, every agent covered.

Skills are plain markdown files. No background daemon, no MCP server, no ports.

How Docmancer Fixes It

Chunk and embed locally. Docmancer splits docs into 800-token chunks and embeds them with FastEmbed, fully on your machine. No embedding API costs, no data leaving your system.

Hybrid retrieval. Queries run dense + sparse (BM25) retrieval in parallel and merge results with reciprocal rank fusion. Dense vectors catch semantic meaning; BM25 catches exact terms like flag names, error codes, and method signatures.

Return only what matches. A query returns 5 chunks by default (a few hundred tokens). The whole site stays indexed; only the relevant slice lands in context.

Concurrent-safe. Multiple CLI calls from parallel agents or different terminals are serialized with a file lock. No corruption.

How It Works

┌──────────────────────────────────────────────────────────────────────────┐
│  DOCMANCER FLOW                                                          │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  INGEST                 INDEX                      RETRIEVE              │
│  ┌────────────┐         ┌────────────┐         ┌──────────────────────┐  │
│  │ GitBook    │         │ Chunk text │         │ docmancer query      │  │
│  │ Mintlify   │   ─►    │ FastEmbed  │   ─►    │ e.g. how to auth?    │  │
│  │ Web docs   │         │ vectors on │         │                      │  │
│  │ Local docs │         │ disk Qdrant│         │ → top matching       │  │
│  │ .md / .txt │         │            │         │   chunks only        │  │
│  └────────────┘         └────────────┘         │                      │  │
│       │                       ▲                └──────────────────────┘  │
│       └───────────────────────┴── dense + sparse (BM25); file lock       │
│                                                                          │
│  SKILL INSTALL                           AGENT                           │
│  ┌──────────────────────────┐            ┌──────────────────────────┐    │
│  │ docmancer install        │            │ Claude Code, Cursor,     │    │
│  │ claude-code, cursor, …   │    ─►      │ Codex, … run the CLI     │    │
│  └──────────────────────────┘            │ via installed SKILL.md   │    │
│                                          └──────────────────────────┘    │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

1. docmancer ingest: fetches docs from GitBook, Mintlify, generic web docs, or local files. Chunks and embeds them locally with FastEmbed. Stores vectors in on-disk Qdrant.
2. docmancer install: drops a SKILL.md into your agent's skills directory. The skill teaches the agent when and how to call the CLI.
3. Agent queries automatically: when your agent needs docs, it runs docmancer query and gets back only the relevant chunks.

Why Local?

Commands

Use --full with docmancer query to return the entire chunk body (default truncates at 1500 characters). Use --limit N to change how many chunks are returned.

Install

Recommended: install pipx with Homebrew, then install docmancer with an explicit supported Python version.

brew install pipx
pipx ensurepath

Open a new shell, then install docmancer:

pipx install docmancer --python python3.13

Supports Python 3.11-3.13. Pass the version explicitly: pipx may pick the wrong interpreter on some machines.

On Apple Silicon, prefer the native Homebrew Python:

pipx install docmancer --python /opt/homebrew/bin/python3.13

Upgrade

pipx upgrade docmancer

If you want to keep a specific Python version, reinstall explicitly:

pipx reinstall docmancer --python python3.13

Install Targets

Use --project with claude-code or gemini to install under .claude/skills/... or .gemini/skills/... in the current working directory.

Configuration

Resolution order: --config → ./docmancer.yaml in the current directory → ~/.docmancer/docmancer.yaml (auto-created on first use).

Configuration Reference

Example docmancer.yaml

embedding:
  provider: fastembed
  model: BAAI/bge-small-en-v1.5

vector_store:
  provider: qdrant
  local_path: .docmancer/qdrant # resolved relative to this file's directory
  collection_name: knowledge_base
  retrieval_limit: 5
  score_threshold: 0.35

ingestion:
  chunk_size: 800
  chunk_overlap: 120
  bm25_model: Qdrant/bm25

Supported Sources

Troubleshooting

pip install succeeds, but docmancer is command not found

This usually means the scripts directory is not on your PATH. The install output will show the path:

WARNING: The script docmancer is installed in '/Users/your-user/Library/Python/3.13/bin' which is not on PATH.

Recommended fix:

brew install pipx
pipx ensurepath
pipx install docmancer --python python3.13

Or confirm the install by running the script directly:

~/Library/Python/3.13/bin/docmancer doctor

pipx install docmancer says No matching distribution found

This means pipx picked an unsupported Python version. docmancer requires Python 3.11–3.13.

pipx install docmancer --python python3.13

If Python 3.13 is not installed:

brew install [email protected]
pipx install docmancer --python python3.13

pipx install fails: Apple Silicon / architecture mismatch

On macOS, pipx and Python can end up on different architectures (arm64 vs x86_64). Use the native Homebrew Python explicitly:

pipx install docmancer --python /opt/homebrew/bin/python3.13

If needed:

arch -arm64 pipx install docmancer --python /opt/homebrew/bin/python3.13

docmancer doctor crashes with pydantic_core or architecture error

The virtualenv was created with the wrong architecture. Recreate it:

deactivate
rm -rf .venv
arch -arm64 /opt/homebrew/bin/python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

Contributing

For development setup and contributing, see CONTRIBUTING.md.

License

MIT License. See LICENSE for details.