Metadata-Version: 2.4
Name: pongogo
Version: 0.3.89
Summary: AI agent knowledge routing system for software development
Project-URL: Homepage, https://github.com/pongogo/pongogo
Project-URL: Documentation, https://github.com/pongogo/pongogo#readme
Project-URL: Repository, https://github.com/pongogo/pongogo
Project-URL: Issues, https://github.com/pongogo/pongogo/issues
Author-email: Pongogo <hello@pongogo.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,knowledge,mcp,routing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: fastmcp>=1.0.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyjwt[crypto]>=2.8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=14.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: claude-agent-sdk>=0.1.41; extra == 'dev'
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-docker>=2.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Description-Content-Type: text/markdown

# Pongogo

Portable AI agent knowledge routing system. Install Pongogo on any repository to get intelligent instruction routing for AI coding assistants.

## Quick Start

```bash
# Install Pongogo
pip install pongogo

# Initialize in your repository
cd your-project
pongogo init
```

This creates a `.pongogo/` directory with configuration and seeded instruction files that help AI assistants understand your project's patterns and practices. The MCP server and hooks run natively — no Docker required.

## Installation

### pip (Recommended)

```bash
pip install pongogo
```

Installs the CLI, MCP server, and all hooks as native entry points. No Docker needed.

### Homebrew (macOS)

```bash
brew tap pongogo/pongogo
brew install pongogo
```

### Docker

For users who prefer container isolation:

```bash
curl -sSL https://get.pongogo.com | bash
```

The installer pulls the Docker image and configures Claude Code to run the MCP server inside a container.

### Requirements

- **Python 3.12+**
- Claude Code installed
- **Docker** (optional — only needed for Docker installation method)

## Usage

### Initialize Pongogo

```bash
pongogo init
```

Creates a `.pongogo/` directory with:

- `config.yaml` - Configuration for enabling/disabling instruction categories
- `instructions/` - Seeded instruction files (42 files across 14 categories)

### Command Options

| Flag | Short | Description |
|------|-------|-------------|
| `--minimal` | `-m` | Install only core instruction categories |
| `--force` | `-f` | Overwrite existing `.pongogo/` directory |
| `--no-interactive` | `-y` | Accept all defaults without prompting |

## Configuration

After initialization, customize `.pongogo/config.yaml`:

```yaml
# Enable/disable instruction categories
categories:
  software_engineering: true
  project_management: true
  agentic_workflows: true
  # ... set to false to disable

# Customize placeholders for your project
placeholders:
  wiki_path: wiki/
  docs_path: docs/
  owner_repo: your-org/your-repo
```

## Instruction Categories

| Category | Files | Description |
|----------|-------|-------------|
| software_engineering | 3 | Git safety, commit formats, Python standards |
| project_management | 6 | Work logging, scope prevention, task management |
| agentic_workflows | 4 | Agent decision making, compliance patterns |
| safety_prevention | 3 | Validation-first execution, systematic prevention |
| trust_execution | 3 | Trust-based execution, feature development |
| _pongogo_core | 10 | Core Pongogo workflows |
| + 8 more categories | | |

## MCP Server Integration

Pongogo includes an MCP (Model Context Protocol) server that routes instructions to AI coding assistants.

### Configure Claude Code

`pongogo init` automatically configures the MCP server and hooks. For manual configuration:

```bash
pongogo setup-mcp

# Preview configuration without changes
pongogo setup-mcp --dry-run
```

### Upgrading

```bash
# Upgrade via CLI (auto-detects pip, Homebrew, or Docker)
pongogo upgrade

# Or from within Claude Code
/pongogo-upgrade
```

## Architecture

Pongogo routes instructions based on context:

```
User message → MCP Server → Semantic Router → Matched Instructions → Agent
```

The routing engine uses:
- **Pattern matching**: Keyword and regex patterns
- **Context disambiguation**: Positive/negative pattern weights
- **Lexicon database**: 329 entries for guidance, friction, and hedging detection

## Status

- ✅ `pongogo init` CLI
- ✅ Seeded instruction files (42 files, 14 categories)
- ✅ MCP server (native via pip/Homebrew, or Docker)
- ✅ Claude Code integration
- ✅ CI/CD with release train (alpha/beta/stable)
- ✅ Three distribution channels: pip, Homebrew, Docker

## License

MIT License - see [LICENSE](LICENSE)

---

**Named after "Pongo"** — the scientific name for the orangutan genus — reflecting the intelligent, collaborative nature of the system.
