⬢ Video Breakdown + Prompt Kit

PopeBot: Secure Self-Improving AI Agent

Architecture breakdown, security model, and ready-to-use prompts extracted from Stephen G. Pope's open-source agent framework

System Architecture

How PopeBot orchestrates jobs through GitHub Actions with full transparency and self-improvement capabilities

💬

Chat Interface Layer

Users interact via Telegram bot or direct API calls (webhook). Sends job requests, receives status updates, and displays completion reports with links back to GitHub PRs.

Telegram Webhook API Voice Messages Postman
⚙️

Job Orchestration

Each request spins up an isolated Docker container via GitHub Actions. The bot creates a plan, requests approval, then executes autonomously. All changes submitted as Pull Requests for review.

GitHub Actions Docker Pull Requests Plan → Approve → Execute
📁

Operating System (Config)

All agent configuration lives in an "operating system" folder within the repo. Markdown files define agent behaviors, skills, templates, and instructions. Fully editable via GitHub UI.

.md configs Templates Cron Jobs Git-versioned
🔄

Self-Improvement Loop

All agent logs are stored in Git. Future jobs can analyze past logs to identify where the bot struggled or excelled, then modify its own codebase and configs to improve performance over time.

Log Analysis Auto-Optimization Git History

Scheduled Tasks (Cron)

The bot can create and manage cron jobs that trigger automatically on schedules. Example: daily financial research report generated before market open, stored as versioned files in the repo.

Cron Syntax Daily/Hourly/Custom Auto-trigger
🔍

Transparency & Audit

Every action is visible through Pull Requests showing exact files changed. Job logs capture the agent's full thought process and decision-making. Nothing runs without visibility.

PR Reviews Full Logs Diff View Audit Trail

⚡ Request Lifecycle

💬
Send Message
Telegram / API
📋
Plan Created
Review & Approve
🐳
Container Spins Up
Docker + GH Actions
🔑
Secrets Injected
Runtime Only
🤖
Agent Executes
Claude + Brave
📝
PR Created
Review Changes
Merge & Report
Telegram Update

Two-Tier Security Model

Credentials are never stored in code — they're injected at runtime from GitHub Secrets with strict separation between what the container needs vs. what the LLM can see

🔴 Outer Layer: GitHub Repository

No credentials stored in code, configs, or job definitions. Repository is safe to fork and share.

No API keys in code No tokens in configs No passwords in jobs

🟠 Middle Layer: Container Secrets (LLM cannot see)

Infrastructure credentials injected at runtime via GitHub Secrets. The LLM process inside the container never has access to these.

GITHUB_TOKEN ANTHROPIC_API_KEY WEBHOOK_SECRET

🟢 Inner Layer: LLM Secrets (LLM can see)

Only the credentials the AI agent actually needs to perform tasks. Minimized attack surface — the LLM only gets what it must have.

BRAVE_SEARCH_API_KEY Custom service credentials Scraping logins (if needed)

🛡️ Key Security Principles

🔒

Runtime Injection

Credentials are never stored in the repository or job definitions. GitHub injects them into the Docker container only when it runs, making the codebase safe to share.

🧱

Isolation per Job

Each job runs in a fresh, isolated Docker container. No shared state between jobs. Container is destroyed after execution completes.

🔐

Webhook Authentication

Event handler validates incoming webhooks with a shared secret. GitHub completion callbacks are authenticated, preventing unauthorized status updates to your chat.

👁️

PR Review Gate

By default, all agent changes require pull request approval before merging to main. You see exactly what files changed before anything takes effect. Configurable for auto-merge.

Ready-to-Use Prompts

Click any use case below to generate a tailored prompt, or use the master PopeBot setup prompt

🏗️ Master: Secure AI Agent Architecture Prompt
You are an expert AI systems architect specializing in secure, self-improving autonomous agents. Design and implement a secure AI bot system with the following architecture: ## CORE ARCHITECTURE Build a self-hosted AI agent that operates through the following pipeline: 1. **Chat Interface** (Telegram bot + REST API webhook) for receiving job requests 2. **Job Orchestration** via GitHub Actions — each request spins up an isolated Docker container 3. **Configuration as Code** — all agent behaviors, skills, and instructions stored as Markdown files in an "operating system" folder within the Git repository 4. **Pull Request Workflow** — all agent-generated changes submitted as PRs for human review before merging 5. **Self-Improvement Loop** — agent logs stored in Git; future jobs analyze past logs to optimize performance ## SECURITY MODEL (Two-Tier Secret Management) Implement strict credential separation: ### Container Secrets (LLM CANNOT access): - GITHUB_TOKEN (repo operations) - ANTHROPIC_API_KEY (LLM inference) - WEBHOOK_SECRET (callback authentication) These are injected at runtime via GitHub Secrets → Docker environment variables. Never stored in code. ### LLM Secrets (LLM CAN access): - BRAVE_SEARCH_API_KEY (web research) - Any task-specific credentials the agent needs for its work Minimized to reduce attack surface. ### Security Principles: - No credentials in repository code or job definitions - Fresh isolated container per job (no shared state) - Webhook authentication for all callbacks - PR review gate before any changes merge to main branch ## JOB LIFECYCLE For each request: 1. User sends message via Telegram or API call 2. Bot creates an execution plan and presents it for approval 3. On approval → GitHub Action triggers → Docker container spins up 4. Secrets injected at runtime from GitHub Secrets 5. Agent executes task (has access to Brave Search, file creation, code modification) 6. All work submitted as a Pull Request with full logs 7. Completion report sent back to chat interface with PR links 8. User reviews and merges PR to apply changes ## SCHEDULED TASKS Support cron job definitions in a configuration file: - Each cron entry specifies: schedule (cron syntax), command, enabled/disabled status - Agent can create new cron jobs as part of task execution - Example: "Daily financial research at 6 AM → read instructions → generate report → commit to repo" ## SELF-IMPROVEMENT MECHANISM - All agent execution logs committed to Git - Create analysis jobs that review past logs for: - Failure patterns and error resolution - Performance bottlenecks - Successful strategies to replicate - Agent can modify its own operating system files to improve future performance ## OUTPUT REQUIREMENTS For any job, the agent should produce: 1. The job definition file (what was requested) 2. Complete execution logs (thought process, API calls, decisions) 3. The actual deliverable (report, code, configuration, etc.) 4. A summary message back to the chat interface Design this system to be forkable, configurable, and secure by default with optional auto-merge for trusted workflows.

Use Case Prompt Generator

Select a use case to generate a PopeBot-style job prompt:

📊 Financial Advisor

Daily pre-market research reports with sector analysis, key movers, and actionable insights

🔍 SEO Content Agent

Automated content generation for local service businesses with multi-city targeting

🕵️ Competitor Monitor

Daily competitor tracking — pricing changes, new features, content updates, social activity

🧑‍💻 Code Reviewer

Automated code review bot that analyzes PRs, suggests improvements, and enforces standards

📰 Newsletter Curator

Daily industry news aggregation, summarization, and newsletter draft generation

📱 Social Media Agent

Content ideation, drafting, and scheduling optimization based on trending topics

💡 Generated Prompt

Technology Stack

Everything used to build and run PopeBot

🐳
Docker
Container isolation
⚙️
GitHub Actions
Job orchestration
📦
GitHub Secrets
Credential management
🔀
Git / PRs
Version control & review
🤖
Anthropic Claude
LLM backbone
🔍
Brave Search
Web research
💬
Telegram Bot API
Chat interface
🌐
ngrok
Local dev tunneling
📮
Postman
API testing
📦
Node.js / npm
Runtime & packages
🧠
OpenAI (Optional)
Voice message transcription
🔧
VS Code
Local development

📋 Installation Requirements

Setup Checklist
1. Fork the PopeBot repo (set to PRIVATE) 2. Clone to local machine: git clone https://github.com/YOUR_USERNAME/popebot.git 3. cd popebot && npm run setup 4. Provide when prompted: ├── GitHub Personal Access Token (actions: read, content: read/write, PRs: read/write) ├── Anthropic API Key ├── OpenAI API Key (optional — enables voice messages) ├── Brave Search API Key (free tier available) └── Telegram Bot Token (via @BotFather) 5. Start event handler: npm run start 6. Start ngrok tunnel: ngrok http [port] 7. Paste ngrok URL into setup wizard 8. Verify Telegram connection with /verify command 9. Send your first job! 🚀

Roadmap

Where PopeBot is headed — current features and planned improvements

Telegram Chat Interface

Full bidirectional chat with plan approval, status updates, and completion reports with GitHub links

GitHub Actions Job Execution

Isolated Docker containers per job with runtime secret injection and PR-based review workflow

Cron Job Scheduling

Agent can create and manage scheduled tasks with standard cron syntax, enabling daily automations

API Webhook Trigger

External job triggering via authenticated API calls, enabling integration with any system

🔨

Persistent Cross-Channel Memory

Unified conversation memory that persists across Telegram, Slack, and other connected chat interfaces

🔨

Production Deployment Guide

Cloud hosting instructions to run PopeBot 24/7 without local machine dependency

📋

Plugin / Skills Marketplace

Repository of pre-built skills and plugins that can be installed to extend bot capabilities instantly

📋

Multi-Channel Support (Slack, Discord)

Expand chat interfaces beyond Telegram to support team collaboration tools