agentic-pydoc

Static Python codebase intelligence for AI agents.

Installation

Requires Python 3.13+.

Install as an isolated tool (recommended):

uv tool install agentic-pydoc

Or with pipx:

python -m pip install --user pipx
python -m pipx ensurepath
pipx install agentic-pydoc

Then verify the install from any directory:

agentic-pydoc --help
agentic-pydoc --version

Development

Contributors clone the repository and sync the environment instead:

git clone <repository-url>
cd agentic-pydoc
uv sync
uv run agentic-pydoc --help

Quick Start

A Git repository with at least one commit is required. Initialize and analyze a Python project:

cd /path/to/python-project
git init
git add .
git commit -m "initial"

agentic-pydoc init             # Create .agentic-pydoc.toml
agentic-pydoc install-skill    # Install the agent skill (optional)
agentic-pydoc scan             # Full analysis + BASELINE = HEAD

This creates .agentic-pydoc/ with the analysis index, modules, symbols, relationships, and the BASELINE file (the SHA of the last documented commit).

Incremental workflow

After code changes, commit and regenerate documentation:

git add .
git commit -m "change feature"
agentic-pydoc docs             # Diff BASELINE..HEAD, update docs, BASELINE = HEAD

docs only analyzes files changed since the baseline commit. Run agentic-pydoc status to inspect HEAD, baseline, and pending changes, and agentic-pydoc check to verify the project is ready.

MCP Server (New!)

Expose codebase intelligence to AI agents via Model Context Protocol:

cd /path/to/python-project
agentic-pydoc-mcp

The MCP server provides 9 tools for progressive codebase navigation:

• list_modules - List Python modules with pagination
• get_module - Get module details with symbols and imports
• find_symbol - Search for symbols by name/pattern
• get_symbol - Get full symbol details (signature, docstring, location)
• get_behavior - Get function behavior (raises, awaits, yields, returns)
• get_callers - Get all callers of a function/method
• get_callees - Get all callees of a symbol
• get_inheritance - Get class inheritance hierarchy
• get_tests - Get test cases for a symbol

See MCP Server Documentation for complete API reference, examples, and integration guide.

Architecture

Agent (LLM)
    ↓
MCP Protocol (JSON-RPC)
    ↓
MCP Server
    ↓
Service Layer
    ↓
Knowledge Navigator (shared with CLI)
    ↓
Knowledge Store
    ↓
.agentic-pydoc/

Both CLI and MCP use the same underlying service layer, ensuring consistent results.

CLI Commands

Analysis Commands

agentic-pydoc init             # Initialize .agentic-pydoc.toml in a Git repo
agentic-pydoc scan             # Full scan, refuse to overwrite existing BASELINE
agentic-pydoc docs             # Incremental update since BASELINE (no --check = apply)
agentic-pydoc check            # Verify repo, config, baseline readiness
agentic-pydoc status           # Show HEAD, BASELINE, changes since baseline
agentic-pydoc update           # Incremental index update from last commit
agentic-pydoc install-skill    # Install the agent skill

Navigation Commands

# Discovery
agentic-pydoc modules                           # List all modules
agentic-pydoc module <name>                     # Get module details
agentic-pydoc find <query>                      # Search for symbols
agentic-pydoc symbols --module <name>           # List symbols in module

# Symbol inspection
agentic-pydoc symbol <symbol-id>                # Get symbol details
agentic-pydoc source <symbol-id>                # Get source code
agentic-pydoc behavior <symbol-id>              # Get behavioral attributes

# Relationship navigation
agentic-pydoc callers <symbol-id>               # Who calls this?
agentic-pydoc callees <symbol-id>               # What does this call?
agentic-pydoc dependencies <symbol-id>          # All dependencies
agentic-pydoc dependents <symbol-id>            # All dependents
agentic-pydoc inheritance <class-id>            # Class hierarchy
agentic-pydoc tests <symbol-id>                 # Associated tests

# History
agentic-pydoc history                           # Git history
agentic-pydoc diff <rev-a> <rev-b>              # Semantic diff

All navigation commands support --format json for programmatic use.

Project Intelligence vs Documentation

Three responsibilities stay separate:

• Source code is the source of truth.
• .agentic-pydoc/ holds machine-readable project intelligence for agents: index.json, state.json, modules/, symbols/, relationships/.
• docs/ holds human-facing documentation only.

agentic-pydoc scan writes the analysis under .agentic-pydoc/ and the machine-oriented renderings under .agentic-pydoc/docs/ by default (output.directory keeps custom locations when configured). It never writes to docs/ by default, and existing docs/ content is left untouched.

Using the Agent Skill

agentic-pydoc init only writes .agentic-pydoc.toml. Install the agentic-pydoc skill separately:

agentic-pydoc install-skill

This installs .agents/skills/agentic-pydoc/SKILL.md (plus the agentic-pydoc-docs and agentic-pydoc-setup skills). Pass --overwrite to replace an existing installation. The skill tells an agent to:

• Prefer MCP when a server is available
• Use CLI navigation commands as fallback
• Read .agentic-pydoc/index.json for project overview
• Treat analysis as context (not documentation)
• Never copy analysis into docs/ or documentation sites
• Read source files when analysis is insufficient

With Docus / create-docs

Run agentic-pydoc init and agentic-pydoc install-skill in the analyzed project, then point create-docs at the project. The skill instructs the agent to use .agentic-pydoc/ (via MCP or CLI) as context for understanding modules and symbols and to write human-oriented documentation in docs/ or the Docus site — not to copy the analysis.

Documentation

• MCP Server - Complete MCP server reference
• MCP Examples - Usage examples and patterns
• MCP Workflow - Agent workflow guide
• MCP Limitations - Known constraints
• API Reference - CLI, models, analyzers
• Incremental Indexing - Architecture details
• Publishing - PyPI token authentication and publishing guide

Testing

# All tests
uv run pytest

# MCP tests only
uv run pytest tests/mcp/ -v

# Specific test suites
uv run pytest tests/mcp/test_errors.py -v
uv run pytest tests/mcp/test_service.py -v
uv run pytest tests/mcp/test_server.py -v
uv run pytest tests/mcp/test_cli_mcp_consistency.py -v

License

MIT