Pepeclaw 🐾

Pepeclaw is a powerful, ready-to-run multi-agent orchestration platform built on 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:

# Using uv tool
uv tool install pepeclaw

# Using pipx
pipx install pepeclaw

Alternatively, install it in a local virtual environment:

pip install pepeclaw

2. Initialization

Initialize the global configuration file:

pepeclaw init

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

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

# 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

Platform Architecture

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

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:

   git clone https://github.com/UltimateStarCoder/pepeclaw.git
   cd pepeclaw
   

2. Sync Dependencies: Create a virtual environment and synchronize dependencies using uv:

   uv sync
   

3. Install in Editable Mode:

   uv tool install --editable .
   

4. Create Releases: Use the built-in interactive release script to bump versions, create git tags, and push changes:

   python scripts/release.py [patch|minor|major]
   

License

This project is licensed under the MIT License. See LICENSE for details.