Architecture breakdown, security model, and ready-to-use prompts extracted from Stephen G. Pope's open-source agent framework
How PopeBot orchestrates jobs through GitHub Actions with full transparency and self-improvement capabilities
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.
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.
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.
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.
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.
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.
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
No credentials stored in code, configs, or job definitions. Repository is safe to fork and share.
Infrastructure credentials injected at runtime via GitHub Secrets. The LLM process inside the container never has access to these.
Only the credentials the AI agent actually needs to perform tasks. Minimized attack surface — the LLM only gets what it must have.
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.
Each job runs in a fresh, isolated Docker container. No shared state between jobs. Container is destroyed after execution completes.
Event handler validates incoming webhooks with a shared secret. GitHub completion callbacks are authenticated, preventing unauthorized status updates to your chat.
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.
Click any use case below to generate a tailored prompt, or use the master PopeBot setup prompt
Select a use case to generate a PopeBot-style job prompt:
Daily pre-market research reports with sector analysis, key movers, and actionable insights
Automated content generation for local service businesses with multi-city targeting
Daily competitor tracking — pricing changes, new features, content updates, social activity
Automated code review bot that analyzes PRs, suggests improvements, and enforces standards
Daily industry news aggregation, summarization, and newsletter draft generation
Content ideation, drafting, and scheduling optimization based on trending topics
Everything used to build and run PopeBot
Where PopeBot is headed — current features and planned improvements
Full bidirectional chat with plan approval, status updates, and completion reports with GitHub links
Isolated Docker containers per job with runtime secret injection and PR-based review workflow
Agent can create and manage scheduled tasks with standard cron syntax, enabling daily automations
External job triggering via authenticated API calls, enabling integration with any system
Unified conversation memory that persists across Telegram, Slack, and other connected chat interfaces
Cloud hosting instructions to run PopeBot 24/7 without local machine dependency
Repository of pre-built skills and plugins that can be installed to extend bot capabilities instantly
Expand chat interfaces beyond Telegram to support team collaboration tools