thepopebot

A skill is a directory containing a SKILL.md file and optional scripts (Bash, Node.js, etc.). The agent learns to use a skill by reading the SKILL.md file and executes the scripts via bash.

Key Characteristics:

• No Build Step: No TypeScript or compilation required.
• Progressive Disclosure: To save context space, only the name and description from the SKILL.md frontmatter are loaded into the system prompt initially. The full instructions are only read by the agent when it determines the skill is relevant to the user's request.
• Cross-Agent Compatibility: Skills are activated via symlinks in a skills/ directory. Because many coding agents (Claude, Pi, etc.) use symlink bridges to this same directory, activating a skill once makes it available to all connected agents.

The agent has broad capabilities including full filesystem access, shell execution, browser automation, package installation, API calls, and software building. It can also modify its own configuration and build new skills.

Skills are lightweight wrappers (typically bash scripts) that provide the agent access to external services. The agent interacts with these by reading their documentation and invoking them via the shell.

thepopebot uses a channel adapter pattern to normalize messages from different platforms (Telegram, Discord, etc.) into a single format. This allows the core AI layer to remain channel-agnostic; it only ever interacts with a standardized message structure.

When a message arrives via a webhook, the adapter:

1. Parses the raw request.
2. Normalizes it into the standard message format.
3. Handles platform-specific UI feedback (like typing indicators or message reactions).
4. Sends the AI's response back to the specific channel.

The agent operates within a Docker container. The primary workspace is located at /home/coding-agent/workspace, which is a live git repository.

Crucial Persistence Rule: Any file you create, move, or download into /home/coding-agent/workspace will be automatically committed and pushed to the repository when the job finishes. You cannot prevent this.

To avoid polluting the git history, use /tmp for all transient working files, such as:

• Downloads
• Screenshots
• Intermediate data
• Scripts
• Generated files

If a tool downloads a file, save it to /tmp and reference it by its path.

Skills can access sensitive information via environment variables.

Setting up API Keys: To provide a key to a skill, add it at Admin > Event Handler > Agent Jobs. The secret will be injected as an environment variable into the Docker container where the skill runs.

Security Model:

• Protected Secrets: Variables with the AGENT_* prefix are filtered from the bash environment by the env-sanitizer extension to prevent accidental leakage.
• LLM-Accessible Secrets: Variables with the AGENT_LLM_* prefix are deliberately left available so skills can use them.
• Discovery: Agents can use the agent-job-secrets skill to list and retrieve available secrets.

A code workspace is a persistent interactive container that allows users to attach via a browser using a WebSocket connection (handled by lib/code/ws-proxy.js with cookie authentication).

Key Characteristics:

• Persistence: Each workspace is tracked in the code_workspaces table (storing repo, branch, codingAgent override, and scope).
• Resilience: The tmux session inside the container survives WebSocket reconnects. If the container itself fails, ensureCodeWorkspaceContainer() is responsible for recreating it using the existing persistent volume.

Background jobs handle file/directory scoping via the --scope flag:

• Inheritance: If the calling agent has a SCOPE environment variable set, the new job defaults to that same scope.
• Override: Use --scope <value> to set a specific scope.
• Clear: Use --scope "" to clear the scope for the new job.

thepopebot operates using a central 'Brain' (your event handler) that manages interactions between interfaces (Browser, Telegram) and execution environments (Docker). It distinguishes between two primary interaction modes:

1. Live chat: Used for quick questions or small edits. The coding agent runs immediately and streams responses to your screen.
2. Agent job: Used for complex tasks (e.g., "Build it. DM me when done."). A background worker launches a fresh Docker container, performs the work, opens a Pull Request, auto-merges, and sends you a Direct Message when complete.

Workspaces allow you to attach a terminal to a persistent container running your coding agent, sharing the same session as your chat.

The maxConcurrency setting (default: 1) limits the number of simultaneous containers for a specific role. All triggers (Manual, Webhook, Cron, File Watch) are subject to this limit via the canRunRole() gate. If the limit is reached, the trigger is rejected.

Use higher concurrency for roles processing independent parallel workloads, and keep it at 1 for sequential tasks.

Automated upgrades are managed by two GitHub Actions workflows that handle dependency updates and environment rebuilding separately.

1. upgrade-event-handler.yml (Manual Trigger): Triggered via workflow_dispatch in the Actions tab. It updates package.json and package-lock.json by running npm install and npm update thepopebot. If a version change is detected, it creates a new branch (e.g., upgrade/thepopebot-<version>-<timestamp>) and opens a PR with auto-merge enabled.

2. rebuild-event-handler.yml (Automatic Trigger): Triggered when an upgrade PR merges into main. It performs the heavy lifting: scaffolding updated templates via npx thepopebot init --no-install, running npm install, committing template changes, pulling the new Docker image, and restarting the container via docker compose up -d.