pongogo 0.3.33
AI agent knowledge routing system for software development
Requires Python: >=3.12
Keywords: agents, ai, knowledge, mcp, routing

# 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.