Metadata-Version: 2.4
Name: pepeclaw
Version: 0.0.5
Summary: Multi-agent system powered by Agno and MCP.
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: agno[os]>=2.6.9
Requires-Dist: aiohttp>=3.13.5
Requires-Dist: anthropic>=0.104.1
Requires-Dist: docker>=7.1.0
Requires-Dist: fastmcp>=3.3.1
Requires-Dist: google-cloud-aiplatform>=1.154.0
Requires-Dist: google-genai>=2.6.0
Requires-Dist: mcp>=1.27.1
Requires-Dist: openai>=2.38.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: reportlab>=4.5.1
Description-Content-Type: text/markdown

# Pepeclaw 🐾

[![PyPI version](https://img.shields.io/pypi/v/pepeclaw.svg)](https://pypi.org/project/pepeclaw/)
[![Python Version](https://img.shields.io/pypi/pyversions/pepeclaw.svg)](https://pypi.org/project/pepeclaw/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Pepeclaw is a powerful, ready-to-run multi-agent orchestration platform built on [Agno](https://github.com/agno-agi/agno) and the Model Context Protocol (MCP). It features consolidated developer agents, shared cross-session learnings, OAuth-based API integrations, and an interactive command-line interface.

---

## Key Features

*   🤖 **Unified Coding Suite**: A consolidated Developer Agent with shell access, file operations, grep search, and native calculation tools.
*   🔌 **Integrated MCP Agent**: A single endpoint managing all developer docs (Agno, Clerk, LiveKit, Svelte) and external service APIs (Convex, Expo, Stripe).
*   🧠 **Shared Learning Machine**: Persistent knowledge graph, user profile extraction, and decision logging synchronized across all agents via a local SQLite database.
*   🔑 **OIDC & OAuth Integration**: Secure browser-based OAuth flows with silent token refresh for platforms like Stripe and Expo.
*   🚀 **FastAPI ASGI Server**: Run your multi-agent system as a production-grade live web API using Agno's `AgentOS`.

---

## Quick Start

### 1. Installation

Install Pepeclaw globally using `uv` (recommended for speed) or `pipx`:

```bash
# Using uv tool
uv tool install pepeclaw

# Using pipx
pipx install pepeclaw
```

*Alternatively, install it in a local virtual environment:*
```bash
pip install pepeclaw
```

### 2. Initialization

Initialize the global configuration file:

```bash
pepeclaw init
```

This creates a settings file at `~/.pepeclaw/.env`. Open it and configure your active provider and API credentials:

```env
# Choose provider: anthropic (default), openai, gemini, or xai
PEPECLAW_PROVIDER=anthropic

# Credentials matching your active provider
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx
XAI_API_KEY=xai-xxx
```

### 3. Start Chatting

Launch a conversation with the consolidated developer agent or teams:

```bash
# Start an interactive coding session
pepeclaw chat coding

# Run queries against all docs and external APIs
pepeclaw chat mcp

# Load the full orchestrated agent team
pepeclaw chat fullstack
```

---

## CLI Reference

| Command | Description |
| :--- | :--- |
| `pepeclaw init` | Setup the global configuration file in your home directory |
| `pepeclaw list` | List all registered agents, teams, and active memberships |
| `pepeclaw serve` | Run the AgentOS server (connect local server to `os.agno.com`) |
| `pepeclaw chat <name>` | Chat in the terminal with an agent or team (e.g. `coding`, `mcp`, `fullstack`) |
| `pepeclaw sessions list` | View past conversation sessions |
| `pepeclaw sessions clear <session_id>` | Clear a specific chat session |
| `pepeclaw auth login <service>` | Run OAuth flows to login and cache tokens (`stripe`, `expo`) |
| `pepeclaw auth clear <service>` | Clear cached OAuth tokens for a specific service |
| `pepeclaw auth status` | Check which external services have cached login tokens |
| `pepeclaw reset --all` | Reset all local data (learning stores, tokens, database, temporary files) |

---

## Platform Architecture

Pepeclaw operates a structured hierarchy of specialized agents orchestrated into collaborative teams:

```text
Full Stack Team (Orchestrator)
├── Code Team
│   ├── Developer Agent (Files, Shell, Math, Git/GH)
│   ├── Filegen Agent (Generates PDF reports and Gemini images)
│   └── Reasoning Agent (Stepwise reasoning & debugging)
├── Deploy Team
│   ├── Developer Agent
│   └── MCP Agent (Coordinates Convex and Expo actions)
├── Research Team
│   ├── Developer Agent
│   ├── Reasoning Agent
│   └── MCP Agent (Queries Svelte, Agno, Clerk, LiveKit docs)
└── MCP Agent (Unified Model Context Protocol access)
```

---

## Agent Configuration

All model assignments are configured centrally in `config.py` using task-specific roles. They are dynamically mapped based on the `PEPECLAW_PROVIDER` environment variable:

*   **`default_model`**: Day-to-day coding, CLI conversations, and general MCP tool use (`Claude Sonnet 4.6`, `GPT-5.3 Codex`, `Gemini 2.5 Flash`, or `Grok 2`).
*   **`reasoning_model`**: Deep stepwise analysis and team orchestrators (`Claude Opus 4.6`, `o3`, `Gemini 3.1 Pro`, or `Grok 3`).
*   **`fast_model`**: High-volume structured learning extraction (`GPT-5 Nano`, `Gemini 2.5 Flash-Lite`, or `Grok 3 Mini`).
*   **`image_model`**: Multimodal generation tasks (defaults to `Gemini 2.5 Flash Image`).

---

## Local Development & Contributing

To run, extend, or build Pepeclaw from source:

1.  **Clone the Repository**:
    ```bash
    git clone https://github.com/UltimateStarCoder/pepeclaw.git
    cd pepeclaw
    ```

2.  **Sync Dependencies**:
    Create a virtual environment and synchronize dependencies using `uv`:
    ```bash
    uv sync
    ```

3.  **Install in Editable Mode**:
    ```bash
    uv tool install --editable .
    ```

4.  **Create Releases**:
    Use the built-in interactive release script to bump versions, create git tags, and push changes:
    ```bash
    python scripts/release.py [patch|minor|major]
    ```

---

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
