The Pope Bot
A self-hosted hub for chat-driven coding, live workspaces, and autonomous pull-request delivery.
Per-dimension scores and reasoning
The evidence describes verified Telegram users, fail-closed webhook validation, AES-256-GCM session encryption, expiring per-job keys, auto-merge path restrictions, and narrowly scoped release-workflow permissions. External actions and credential uses are also reasonably visible. Deductions apply because the agent can launch containers, commit and push code, open and automatically merge PRs, while the setup wizard generates a PAT; the supplied material does not show per-action confirmation, default token scopes, or a complete least-privilege model. Dependencies use broad compatible ranges without supplied lockfile, audit, signing, or vulnerability-response evidence. Git/PR and upgrade-recovery paths offer partial reversibility, but no dedicated rollback after automatic merging is demonstrated. Authorship, licensing, and release naming are clear, although publisher identity is unverified and is credited only as repository attribution.
The README, package metadata, and release workflow are broadly consistent about the two-layer design, container images, version, and supported agents. Upgrade recovery, a Windows SQLite failure, and failed-release cleanup are documented. Deductions reflect the absence of evidence for runtime retries, health checks, error taxonomy, or comprehensive failure messages. The system depends on model providers, GitHub, Docker, npm, and sometimes a tunnel; provider choice improves substitution but does not establish end-to-end graceful degradation. Changelog generation has commit-message and generic fallbacks, but these cover only the release process.
The material clearly separates live chat, background jobs, agent mode, and code mode, while addressing local and VPS deployment, browser and Telegram access, many model providers, and six coding-agent backends. This thoroughly establishes audiences and scenarios. Deductions apply because broad claims such as doing almost anything and supporting any LLM are not paired with strict capability boundaries. Triggers, crons, and per-run overrides are mentioned without their actual configurations, precedence, or conflict behavior. Prerequisites and the ngrok exception are clear, but there is no full platform compatibility or resource-requirement matrix, and Windows coverage is limited to one known issue.
The README has strong architecture, installation, configuration, upgrade, security, known-issue, and documentation navigation. Prerequisites and setup steps are concrete, while the complete MIT text agrees with package metadata, justifying full license credit. Deductions apply because examples are chiefly commands and diagrams rather than complete end-to-end cases, and FAQ coverage is limited. Known risks include public development endpoints, no rate limiting, no TLS on the local hop, and a Windows SQLite issue, but limitations are not comprehensively catalogued. Semantic versions, stable/beta upgrade paths, and an automated release workflow exist, although release notes are LLM-generated and may fall back to a generic message. A named author, support link, and maintainer documentation establish an update path, but governance, response commitments, and verified organizational responsibility are absent.
The product combines chat, persistent workspaces, isolated background jobs, PR handling, and completion notifications into a plausibly usable workflow, with multi-provider and multi-agent integration offering meaningful consolidation. Deductions apply because the supplied material is primarily descriptive and provides no static evidence quantifying output quality, time saved, or incremental benefit over alternatives. It mentions subscriptions, API billing, self-hosting, and a free tunnel option, but gives no expected model, infrastructure, tunnel, or maintenance costs and shows no budget or usage controls for autonomous jobs.
Core claims are traceable to README architecture, configuration routes, and security statements, with partial corroboration from package exports, dependencies, version metadata, and the workflow that builds images and publishes releases. Deductions apply because the referenced security, architecture, auto-merge, and upgrade documents are not supplied, nor is the implementation of the critical paths; encryption, authentication, path restrictions, and no-data-loss claims therefore cannot be fully checked. Marketing summaries are somewhat separated from concrete configuration instructions, but several broad capability and security assertions are not explicitly labeled as unverified claims.
- Background agents can commit, push, and automatically merge code. Review ALLOWED_PATHS, branch protection, PAT scopes, and per-operation approval policy before enabling this behavior.
- A tunneled local deployment exposes development-server endpoints; the source explicitly warns that there is no rate limiting and no TLS on the local hop. Do not expose a sensitive environment this way without additional controls.
- API keys, OAuth tokens, and the Telegram bot token are centralized in system configuration. Independently verify secret storage, log redaction, rotation, revocation, and backup-recovery behavior.
- The dependency surface is large, and no lockfile or security-scan results are supplied. Pin resolved versions and audit dependencies and container images before deployment.
- The package test script explicitly reports “No tests yet.” This does not reduce criteria reserved outside this static assessment, but upgrades and automatic merging should be validated in an isolated repository first.
- Release notes may be generated by an LLM and can fall back to commit subjects or generic text; do not treat them alone as complete or precise change evidence.
What does this agent do, and when should you use it?
The Pope Bot combines a personal agent, coding environment, and communications layer in one self-hosted application. It exposes built-in web chat and a verified-user Telegram integration, with Slack and Discord described as upcoming. Users can select Claude Code, Codex, Gemini, OpenCode, Pi, or Kimi as the coding backend and connect providers including Anthropic, OpenAI, Google, DeepSeek, Mistral, xAI, OpenRouter, and NVIDIA. Live chat can share a session with an in-browser terminal, while longer jobs run inside fresh Docker containers and produce branches, commits, and pull requests. GitHub Actions can auto-merge completed work and notify the user, with execution remaining on the user's hardware, repository, and credentials under an MIT license.
Requests arrive through browser chat or from a verified Telegram user and are routed to an event handler that selects the coding agent, restores the session, and chooses an execution path. Live chat runs the configured coding agent immediately and streams its response; code mode also targets a selected repository and branch and can attach a browser terminal to a persistent Docker workspace sharing that session. An Agent job creates an agent-job/<id> branch, launches a fresh Docker container, and lets the coding agent edit files, commit, push, and open a pull request. The auto-merge.yml workflow can merge that PR, and notify-pr-complete.yml sends a completion message. A separate Helper LLM handles one-shot chat titles, job titles, and PR-merge summaries, while agent_backend and llm_model can override the default backend for crons, triggers, or chained jobs.
- A solo developer can request a small repository change through web chat or Telegram, then enter the browser terminal and continue in the same coding session.
- A developer delegating longer work can launch a background Agent job and receive a message after the resulting pull request is completed.
- Someone maintaining several projects can use code mode to select a repository and branch per session while reserving agent mode for the bot's own configuration, skills, and operations.
- A team with accounts across several model providers can centralize credentials while assigning different models to interactive coding and lightweight title or summary generation.
- A Claude Pro or Max subscriber can authenticate Claude Code with an OAuth token and use that subscription for both live chat and background jobs.
- An organization that wants its repositories, secrets, and execution environment on its own infrastructure can deploy the application locally or on a VPS with Docker Compose.
What are this agent's strengths and limitations?
- It unifies browser chat, verified Telegram messaging, an interactive browser terminal, and background code delivery under the same session-oriented event handler.
- It explicitly supports six coding-agent backends, numerous model providers, and arbitrary OpenAI-compatible endpoints instead of requiring one model vendor.
- Background jobs cover the full path from isolated Docker execution through branch creation, commits, pull requests, optional auto-merge, and user notification.
- It runs on user-controlled hardware, repositories, and tokens, with documented AES-256-GCM session encryption, fail-closed webhook validation, and expiring per-job API keys.
- Its upgrade design separates replaceable managed files from protected user files and supplies
audit,diff, andresetcommands for deliberate template synchronization.
- Adoption requires Node.js, Git, GitHub CLI, Docker Compose, GitHub access, and credentials for the chosen model providers, creating a meaningful setup and maintenance burden.
- Local deployments must be reachable for GitHub webhooks and Telegram; the documented tunnel setup exposes development endpoints without rate limiting and has no TLS on the local hop.
- Telegram is the only documented external chat integration currently available; Slack and Discord are still described as upcoming.
- Automatic merging increases the potential impact of an incorrect agent change, so operators must configure path restrictions and remain responsible for infrastructure security.
- Windows installations may encounter SQLite
SQLITE_IOERR_SHMOPENwhen antivirus software or cloud-synced directories interfere with shared-memory files.
How do you install or deploy this agent?
Install Node.js 18+, Git, GitHub CLI, Docker, and Docker Compose. A local installation without port forwarding also needs an ngrok account and authtoken. Run:
mkdir my-agent && cd my-agent
npx thepopebot@latest init
npm run setupThe interactive wizard checks prerequisites, creates a GitHub repository, generates a PAT, configures the application URL, and starts Docker. Visit APP_URL when it completes. For a local tunnel, run ngrok http 80; if its URL changes, run npx thepopebot set-var APP_URL <new-url> and register the Telegram webhook again.
How do you use this agent?
After signing in at APP_URL, configure three sections in order. Add provider API keys at /admin/event-handler/llms; select the provider and model for titles and merge summaries at /admin/event-handler/helper-llm; then choose Claude Code, Pi, Codex, Gemini, OpenCode, or Kimi and its model at /admin/event-handler/coding-agents. You can then issue live requests through web chat, choose a repository and branch in code mode, open a workspace terminal sharing the chat session, or request a background job that returns a pull request and completion notification. To add Telegram, paste a BotFather token into /admin/event-handler/telegram and register its webhook. Generate a one-time code at /profile/telegram, send /verify <code> to the bot, use /session to list active threads, and /session <id> to switch the destination thread.
FAQ
Does it require one specific model provider?
Can a Claude Pro or Max subscription be used instead of API billing?
@anthropic-ai/claude-code, run claude setup-token, and add the resulting sk-ant-oat01- token to the Claude Code OAuth configuration. The same token supports live chat and background jobs.What access does a background job have to the repository?
agent-job/<id> branch, runs the coding agent in Docker, modifies files, commits and pushes the result, and opens a pull request. Configured workflows may then merge the PR and send a notification.Will upgrades overwrite local customizations?
docker-compose.yml, and .gitignore are replaced. User-controlled files such as agent-job/SYSTEM.md, CRONS.json, TRIGGERS.json, agents, skills, .env, and secrets are documented as protected from upgrades.