PopeBot: An Autonomous AI Agent Framework

PopeBot: An Autonomous AI Agent Framework

Metadata

At a Glance

The repo IS the agent. Every action is a git commit. Fork the repo to clone the agent. Free compute via GitHub Actions. Self-evolving through its own PRs. It's like OpenClaw but with git as the backbone instead of a persistent process.

Quotes

Want to clone your agent? Fork the repo.

— PopeBot design philosophy

Every change is auditable and reversible. The git log IS the agent's memory.

— Stephen G. Pope

One task or hundreds in parallel

— all on GitHub Actions free tier. — PopeBot architecture

Sam's TLDR

PopeBot by Stephen G. Pope is an autonomous AI agent framework where the repo IS the agent. Every action is a git commit. Want to clone your agent? Fork the repo. It uses a clever two-layer architecture: a Next.js Event Handler (chat, Telegram, cron, webhooks) creates job branches on GitHub, which trigger GitHub Actions to spin up Docker containers running the Pi coding agent. The agent works, commits results, opens a PR, and auto-merges. Free compute via GitHub Actions. Self-evolving through its own PRs. 780 stars, 393 forks, MIT licensed. It's like OpenClaw but with git as the backbone instead of a persistent process.

Key Points

• Core idea: The repository IS the agent. Every action is a git commit. Fork the repo = clone the agent (code, personality, scheduled jobs, full history). [1]
• Free compute: Uses GitHub Actions free tier for running agent jobs. One task or hundreds in parallel. [1]
• Self-evolving: The agent modifies its own code through PRs. Every change is auditable and reversible. [1]

Architecture

How a Job Runs

User sends a message (web chat, Telegram, webhook, or cron fires)

Event Handler creates a job/uuid branch via GitHub API

GitHub Actions detects branch → runs run-job.yml

Docker container spins up with Pi coding agent + Puppeteer + Chromium

Agent does the work, commits results, opens a PR

auto-merge.yml checks merge policy → squash merges

User gets a notification (Telegram or web)

Config Files — The Agent's "OS"

Three Action Types

Security Model

• Protected secrets (AGENT_*) are exported as env vars but filtered from LLM's bash via the env-sanitizer extension
• LLM-accessible secrets (AGENT_LLM_*) are available to the agent for things like browser logins and skill API keys
• echo $ANTHROPIC_API_KEY returns empty — the agent can use the SDK but can't read the key
• Auto-merge respects ALLOWED_PATHS — by default only /logs can be auto-merged
• API keys are database-backed, SHA-256 hashed, timing-safe verified

Interaction Methods

Skills

Skills live in .pi/skills/ and extend the agent's capabilities. Bundled skills include Brave Search and browser tools (Puppeteer + headless Chrome). The Pi skill guide is in config/PI_SKILL_GUIDE.md.

Setup

Three steps:

mkdir my-agent && cd my-agent && npx thepopebot@latest init — scaffolds Next.js project

npm run setup — wizard handles prerequisites, GitHub repo, PAT, API keys, secrets

docker compose up -d — starts the agent

Requires: Node.js 18+, Git, GitHub CLI, Docker, ngrok (for local dev).

Multi-Model Support

Event Handler and Docker Agent can run different LLMs independently. Mix providers per role — Claude for chat, cheaper model for long-running jobs. Supports Anthropic, OpenAI, Google, and custom OpenAI-compatible endpoints (Ollama).

Comparison to Our Setup (Sam/Richard)

What We Could Steal

• Git-as-backbone: Every action as a commit is brilliant for auditability. We could log agent actions as git commits instead of (or in addition to) Mongo.
• Auto-merge with ALLOWED_PATHS: Smart safety net — agent can only auto-merge changes to certain directories.
• Secret filtering from LLM bash: The env-sanitizer pattern is worth adopting. SDKs can read env vars but the LLM can't echo them.
• Action types: The agent/command/webhook distinction is clean. Our orchestrator could benefit from lightweight command tasks that don't need a full agent.
• SOUL.md as identity: They use exactly the same pattern we do — personality, values, and behavior in a markdown file.

Full Summary

PopeBot is Stephen G. Pope's open-source autonomous AI agent framework that uses a clever insight: make the git repository the agent itself. Every action the agent takes is a git commit. Want to back up your agent? It's already version controlled. Want to clone it? Fork the repo. Want to see what it did at 3am? Check the git log.

The architecture is a two-layer system. A Next.js Event Handler runs persistently and handles all inbound communication — web chat, Telegram messages, webhook calls, and cron schedules. When a task needs autonomous execution, the Event Handler creates a job branch on GitHub. GitHub Actions detects the branch and spins up a Docker container running the Pi coding agent (with Puppeteer for browser automation). The agent works, commits its results, opens a PR, and the auto-merge workflow handles the rest. The user gets a Telegram notification when it's done.

The setup is polished — a three-step wizard handles everything from GitHub repo creation to API key management. The security model is thoughtful: secrets are exported as env vars but filtered from the LLM's bash environment via a custom extension, so the agent can use SDKs but can't leak keys. Auto-merge respects configurable path restrictions.

What makes it interesting compared to OpenClaw: it's git-native (not just a persistent process), it gets free compute via GitHub Actions, and every change is auditable/reversible. The tradeoff is latency — spinning up a Docker container per job takes longer than a persistent agent. But for tasks that take minutes to hours, that overhead is negligible.

The community is smaller than OpenClaw (780 stars vs 140k) but the architecture is arguably more elegant for developer use cases. Stephen Pope runs an "AI Architects" community on Skool and has an active YouTube presence teaching people to build with it.

For our setup, the most transferable ideas are: git-as-audit-log, the secret filtering pattern, and the clean agent/command/webhook action type distinction. We already share the SOUL.md and SKILL.md patterns.