pepeclaw 0.0.4

Multi-agent system powered by Agno and MCP.

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

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:

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.