PB Pillbug
Docs GitHub

Async Python agent runtime

Pillbug

([[[[[:){

Run a fleet of small AI agents —

each with the model, tools, and channels

that job actually needs.

Get started View on GitHub

Why Pillbug

Run Single or Fleet

Each runtime is small, single-purpose, and disposable. Combine with A2A into a Fleet of agents.

Reach where users already are

Telegram, Matrix, Slack — every channel is a plugin package.

Workspace-sandboxed tools

File reads, edits, search, command execution, scheduling, and URL fetches all live behind a local scoped MCP server.

Production posture by default

Non-root container, reloadable security patterns, approval-gated mutating tools, structured JSON logs.

Backend flexibility per agent

Gemini/Vertex natively; llama.cpp, vLLM, Ollama, and LiteLLM through the bundled OpenAI-compatibility proxy. Mix tiers across the fleet.

Embedded scheduler & skills

Background agent tasks plus workspace skill discovery.

Highlights

  • Async runtime with debounced inbound message handling
  • Native audio recognition and vision via multi-modal Gemini
  • Local MCP server for file, search, command, and fetch tools
  • Built-in session commands, summarization, and planning
  • Optional packages: A2A, Telegram, Slack, Matrix, WebSocket, dashboard
  • Per-workspace AGENTS.md instructions

Quickstart

Requires Python 3.14+, uv, and a Gemini API key.

git clone https://github.com/m0nochr0me/pillbug.git
cd pillbug
uv sync --locked
export PB_GEMINI_API_KEY=your_api_key
./run.sh