pkgq

pkgq

[][pypi] [][pypi] [][uv] [][ci] [][coveralls] [][license]

Make your Python package discoverable for AI coding agents in 3 steps.

What is PACKAGE.md?

PACKAGE.md is a informally proposed documentation standard for Python packages optimized for AI agents. Unlike README.md (written for humans), PACKAGE.md provides structured, scannable content that coding agents can quickly understand:

• Purpose - What the package does in one line
• Key Components - Classes, functions, and their signatures
• Common Patterns - Code examples for typical use cases
• Migration Guides - How to upgrade between versions

When you add PACKAGE.md to your repository root, coding agents using pkgq can instantly understand your package's capabilities.

Quick Start for Package Authors

3 steps to make your package discoverable:

# 0. Add the marketplace (one-time setup)
claude plugin marketplace add christophevg/marketplace

# 1. Get the plugin
claude plugin install [email protected]

# 2. Generate documentation
/pkgq:create

# 3. Commit and push
git add PACKAGE.md && git commit -m "docs: add PACKAGE.md" && git push

Done! Your package is now discoverable by coding agents using the pkgq tool or MCP server.

Add the badge to show your package supports AI agents:

[![PACKAGE.md](https://img.shields.io/badge/pkgq-PACKAGE.md-blueviolet)](https://github.com/christophevg/pkgq#readme)

For Package Users

Installation

pip install pkgq

# For MCP server support
pip install "pkgq[mcp]"

Python Module

from pkgq import find

# Find package documentation
result = find("yoker")
print(result.content)

# Check for updates
result = find("yoker", from_version="1.5.0")

Command Line

% pkgq find yoker --save | head -15
Saved to: /Users/xtof/.cache/pkgq/packages/yoker
yoker 0.4.0 (cached)
Source: github:christophevg/yoker

                              Yoker

A Python agent harness with configurable tools and guardrails - one who yokes
agents together.

Overview

Yoker is a library-first, event-driven agent harness for Python that integrates
with Ollama. It provides a transparent, configurable runtime for AI agents with
structured tool execution, guardrails, and event emission. Unlike CLI-first
agent frameworks, Yoker is designed to be embedded in applications with full
visibility into agent operations.

% pkgq cache --list
Cached packages (3):
  pkgq 0.3.2 (pypi)
  roomz 0.2.0 (github:christophevg/roomz)
  yoker 0.5.0 (github:christophevg/yoker)

Yoker Tool

When you're using yoker as your agent harness, you can simply include the pkgq package in your environment and ask yoker to load it as a plugin...

% uvx --with pkgq yoker --with pkgq

╭───────────────────────────────── Plugin: pkgq ──────────────────────────────────╮
│ Plugin: pkgq                                                                    │
│                                                                                 │
│ Tools:     pkgq:find                                                            │
│ Skills:    pkgq:create, pkgq:update                                             │
│ Agents:    (none)                                                               │
│                                                                                 │
│ Plugins can execute code on your system.                                        │
│ Only load plugins you trust.                                                    │
│                                                                                 │
│ Load this plugin? [y/N]:                                                        │
╰─────────────────────────────────────────────────────────────────────────────────╯

y

To trust this plugin permanently, add to your yoker.toml:

  [plugins.trusted]
  pkgq = true