thepopebot: a Next.js event handler, a Docker coding agent, and a PAT it generates for you
The Pope Bot is an autonomous AI agent that you can configure and build to do just about anything you want, all day, everyday, 24/7.
At a glance
- What is it?
- stephengpope/thepopebot is a scaffold that pairs a web event handler with containerised coding agents, reached over Telegram or a browser. Its own file is uneven in the places that matter: the architecture diagram repeats a bullet, the flow chart stops mid arrow, the upgrade section promises three commands and lists four, and the homepage is a paid community.
- Who is it for?
- Read this one as a product shaped around a single bet: that the interesting part of an agent is a long background job that opens a pull request, not a chat box. It fits a solo builder or a small team that wants a hosted bot on its own infrastructure with its own tokens, and Telegram as the remote control.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 6 months ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- stephengpope/thepopebot1,857 ★ · -2
| Repository | 2026-09-11 | 2026-11-21 |
|---|---|---|
| stephengpope/thepopebot | 1.9k | 1.9k |
-2 Stars in the last 71 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two layers, and the package exports both of them
The architecture is stated in the package description rather than in prose: a two layer design of a Next.js event handler plus a Docker agent. The published package is `thepopebot` at version 1.2.82, an ES module with the CLI mapped from `./bin/cli.js` and the entry point at `api/index.js`. Its export map is unusually long for a command line tool and names thirty subpaths, from `./auth` and `./auth/actions` through `./chat`, `./chat/telegram-profile`, `./code/ws-proxy`, `./voice`, `./cluster/stream` and `./containers/logs` to `./oauth/providers` and `./maintenance`. Note what `./chat` resolves to: `./lib/chat/components/index.js`, so user interface components from the web layer travel inside a package that also builds a container image. The published file list is `bin/`, `lib/`, `api/`, `config/`, `setup/`, `templates/` and `drizzle/`, which means the database migration directory ships to npm alongside the scaffolder, and `drizzle.config.js` sits at the root of the tree next to `api/`, `bin/`, `docker/`, `setup/`, `templates/` and `web/`.
The architecture diagram repeats a bullet and the flow chart stops
The file opens with an ASCII picture of three doors and one brain, and it has two visible problems. The list inside the brain box names picking the coding agent twice, as two separate bullets, then remembers the session and runs Docker for you. The three doors feeding it are browser chat, Telegram marked as verified per user, and code, where a live terminal attaches. The second diagram, the one for when you ask for a job, is worse: it runs from you through chat to an event handler that creates an `agent-job/<id>` branch, launches a Docker container locally with your chosen agent, and has the agent commit, push and open a pull request. Then it draws a downward arrow into an empty box and stops. The comparison table above it says the job goes on to auto-merge and send you a direct message, so the picture is missing its last two steps rather than the feature being absent. Neither defect changes the design, and both are the kind of thing that costs a reader a minute.
chatMode decides which repository the conversation touches
Chat is split by mode, and the mode is a repository choice rather than a tone choice. In `agent` mode the conversation runs against your bot's own repository, which is where config, skills and operations live, so you are talking to the bot itself. In `code` mode it runs against any repository and branch you pick, which is where real coding sessions happen. Two execution paths sit on top of that split. Live chat is for quick questions and small edits: the coding agent runs immediately and streams to your screen. An agent job is the background form, triggered by something like Build it, DM me when done, where a worker opens a pull request, merges it and messages you at the end. The live coding workspace is the third piece: open one from any code mode chat and the browser attaches a terminal to a persistent container running whichever coding agent you chose, and the workspace and the chat deliberately share one session, so a question asked in chat is still the context when you hop into the terminal.
Three admin screens have to be filled in a fixed order
After the wizard finishes you sign in at your `APP_URL` and configure three things, and the order matters because each one constrains the next. Providers live at `/admin/event-handler/llms`, where you add API keys for the LLM providers you want, and the file states that everything else pulls from those credentials. The helper LLM lives at `/admin/event-handler/helper-llm` and is a second, separate model choice used only for one-shot calls: chat titles, agent job titles, and pull request merge summaries. Only providers whose keys were added in the first step appear there, which is why the order is fixed. The coding agent lives at `/admin/event-handler/coding-agents`, and this is the one selection that decides a lot: whichever agent you pick drives live chat, code workspaces and background agent jobs, and you configure its model on the same screen. Telegram at `/admin/event-handler/telegram` is optional. The chat feature line also names Slack and Discord as coming soon, which is the kind of claim worth checking against the release notes before planning around.
A local install needs a public tunnel and a token it mints itself
The prerequisite table asks for Node.js 18 or newer, Git, the GitHub CLI, Docker with Docker Compose, and ngrok with a free account and an authtoken, with a footnote that ngrok is only needed for local installs without port forwarding and that VPS or cloud deployments do not need it. Installation is two commands, a scaffold and a wizard:
mkdir my-agent && cd my-agent
npx thepopebot@latest initThe reason for the tunnel is stated plainly: a local server has to be reachable from the internet so GitHub webhooks and Telegram can reach it. The wizard is what closes that loop, checking prerequisites, creating a GitHub repository, generating a personal access token, configuring your URL and starting Docker, after which you run `npm run setup` and visit your `APP_URL`. Two details deserve attention. A credential is created on your behalf without you pasting one anywhere, and the URL is baked into webhook registrations, so when the ngrok address changes the file tells you to run `npx thepopebot set-var APP_URL <new-url>` and re-register the Telegram webhook from the admin page. A rotating tunnel URL is therefore a recurring maintenance item, not a one time setup step.
Upgrade replaces docker-compose.yml and .gitignore every time
The file divides your project into two sets, and the division has consequences. Named as always replaced with the latest version on every init and upgrade are `.github/workflows/`, `docker-compose.yml` and `.gitignore`. Named as never touched by upgrade are `agent-job/SYSTEM.md`, `agent-job/CRONS.json`, `event-handler/TRIGGERS.json`, `agents/`, `skills-library/`, `skills/`, `.env` and secrets. The honest summary in the file is that you never lose your work but you might miss a useful template change. Four commands exist to close that gap: `npx thepopebot audit` shows what has drifted from the templates, `npx thepopebot diff <file>` shows the diff for one file, `npx thepopebot reset <file>` replaces one file with the latest template, and `npx thepopebot reset-all`, marked as nuclear, wipes local edits and restores everything. The prose introducing them says three commands and then lists four, and the ASCII boxes that pair the two file sets are drawn with misaligned borders so the columns read as interleaved. Both are cosmetic, but the first one understates what you can do.
Two tags on one day, and the pinned example is ten versions behind
The release history explains the version number. v1.2.78 was published on 2026-05-07, v1.2.81 on 2026-05-13 at 06:09 UTC and v1.2.82 the same day at 20:49, and the package version in the build configuration reads 1.2.82. Two patch tags on a single day at patch level 82 says the project releases continuously and increments strictly, which is consistent with a scaffold that has to ship template changes often. The last push recorded for the repository is 2026-05-13, the same day as the newest tag, so no commits have landed since. The upgrade command takes three forms: `npx thepopebot upgrade` for the latest stable release, `npx thepopebot upgrade @beta` for the beta channel, and `npx thepopebot upgrade 1.2.72` for a specific version. That last example is the one to notice, because 1.2.72 is ten patch versions behind the tag that exists now, which makes it a useful demonstration of the pinning path and a poor one to copy as your starting version.
The homepage is a paid community, and the support link has no text
The repository's declared homepage is a Skool community rather than a documentation site, and the README links to the same place twice under the phrase get priority support. It also carries a bare anchor element pointing at that URL with nothing inside it, which renders as an invisible link in a Markdown viewer. Meanwhile a `docs/` directory exists in the tree and `CONTRIBUTING.md`, `CHANGELOG.md`, `CLAUDE.md` and `.claude/` sit at the root, so the written material is in the repository even though the front door leads elsewhere. The model lists explain the shape of the product. Eleven chat providers are named, Anthropic through NVIDIA, followed by any OpenAI compatible endpoint, and six coding agents are offered: Claude Code, Codex, Gemini, OpenCode, Pi and Kimi. Telegram is the chat integration available now, with the built in web chat alongside it, and Slack and Discord named as coming soon.
Editorial conclusion
Read this one as a product shaped around a single bet: that the interesting part of an agent is a long background job that opens a pull request, not a chat box. It fits a solo builder or a small team that wants a hosted bot on its own infrastructure with its own tokens, and Telegram as the remote control. It does not fit an environment where an operator cannot expose a public URL, because GitHub webhooks and Telegram both require that and the answer given is a tunnel. Before you scaffold one, check four things. Read what `upgrade` overwrites: `.github/workflows/`, `docker-compose.yml` and `.gitignore` are replaced every time, so keep your copies outside the tree. Read what the wizard does on your behalf, since it creates a GitHub repository and generates a personal access token without you pasting one. Decide which repository a chat is pointed at, since `chatMode` decides that per conversation. And check the dates, because the last push recorded for this repository is 2026-05-13 and the newest tag is v1.2.82 from the same day, which is nearly five months of no recorded commits against a project that ships a beta upgrade channel.
Frequently asked questions
What does thepopebot need installed before setup?
Node.js 18 or newer, Git, the GitHub CLI, Docker with Docker Compose, and ngrok with a free account and an authtoken. ngrok is only needed for local installs that have no port forwarding, since VPS and cloud deployments do not need it.
What is the difference between live chat and an agent job in thepopebot?
Live chat runs the coding agent immediately and streams to your screen for quick questions and small edits. An agent job runs in a background worker that creates an agent-job/<id> branch, commits, pushes, opens a pull request, auto-merges and messages you when it is done.
How do I keep my edits when I upgrade thepopebot?
agent-job/SYSTEM.md, agent-job/CRONS.json, event-handler/TRIGGERS.json, agents/, skills-library/, skills/, .env and secrets are never touched by an upgrade, while .github/workflows/, docker-compose.yml and .gitignore are always replaced. The audit, diff, reset and reset-all commands let you inspect drift and pull template changes back.
Does a local thepopebot install have to be reachable from the internet?
Yes, because GitHub webhooks and Telegram both need to reach it. The file says to expose the server with ngrok http 80, then to run npx thepopebot set-var APP_URL <new-url> and re-register the Telegram webhook whenever that address changes.
Which LLM providers and coding agents can thepopebot use?
For chat, Anthropic, OpenAI, Google, DeepSeek, MiniMax, Mistral, xAI, Kimi, OpenRouter, NVIDIA, or any OpenAI-compatible endpoint. As the coding agent, Claude Code, Codex, Gemini, OpenCode, Pi or Kimi, chosen on the coding-agents admin screen.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/stephengpope-thepopebot)Star history chart for your README
[](https://hysenlabs.com/projects/stephengpope-thepopebot)Was this useful?