Community-contributed plugins, packages, scripts, skills, and lessons for gptme.
If gptme is the engine and gptme-agent-template is the chassis, this repo is the parts catalog: everything you need to assemble a full-featured persistent agent — retrieval and memory, a task system, email and social messaging, real-time voice, GitHub automation, run loops for autonomous operation, and the observability to keep it all honest.
| Layer | Repo | What it provides |
|---|---|---|
| Engine | gptme | The agent runtime: CLI + server/web UI, built-in tools (shell, tmux, patch, python, browser, vision/computer use, gh, rag, todo, MCP client, autocommit/precommit, …), plugin & hook system |
| Chassis | gptme-agent-template | Workspace template for persistent agents: identity files, journal, tasks, lessons, knowledge base |
| Parts | gptme-contrib (this repo) | Plugins, packages, scripts, skills, and lessons you compose on top |
Check gptme core before reaching here. Core already ships a lot, notably the extensive gptme-util CLI with subcommands for context (index, retrieve, search-conversations, git, tree, journal), token counting, chat search, models/providers, LLM helpers, tools, prompts, skills, hooks, MCP, status, snapshots, and session resume. See gptme-util docs. If a capability isn't in core or here, it may exist as a community plugin — see Discover more.
A capability-oriented map of this repo. Each entry links to a plugin (plugins/), package (packages/), or script collection (scripts/) below.
| Capability | Components |
|---|---|
| Retrieval & memory | gptme-rag (vector/semantic search, ChromaDB), gptme-wisdom (BM25 reference-book index) + gptme-wisdom-mcp, gptme-codegraph (structural code retrieval), gptme-retrieval (automatic context retrieval), gptme-user-memories, gptme-cc-memory |
| Tasks & work supply | gptodo (task CLI + work queues), gptme-gptodo (coordinator-mode delegation) |
| gptmail — universal email for agents, incl. agent-to-agent messaging | |
| Chat & social | gptme-whatsapp, gptme-forum (git-native agent forum), discord / telegram / twitter / bluesky scripts |
| Voice | gptme-voice (real-time voice via OpenAI/Grok Realtime APIs), gptme-tts (local Kokoro TTS) |
| GitHub | github scripts (context, notifications), github_hygiene, github_resolver; core's gh tool |
| Autonomous operation | gptme-runloops (run loop framework), gptme-gupp (work persistence), gptme-ralph (iterate with context reset), gptme-coordination (work claims, message bus), credential-slots + gptme-subscription (credential rotation, capacity-aware routing), gptme-backoff |
| Context management | gptme-ace, gptme-attention-tracker, gptme-headroom-compressor, gptme-tooloutput-trimmer |
| Observability & analytics | gptme-sessions, gptme-usage, gptme-dashboard, gptme-activity-summary, gptme-daily-briefing, aw-watcher-agent (ActivityWatch), status scripts |
| Safety & audit | gptme-action-receipts (hashed audit ledger), dotfiles (global git hooks), agent-write-loss-scan, workspace_validator |
| Learning & self-improvement | lessons/, skills/, gptme-lessons-extras, gptme-lessons-mcp (lessons for any MCP client) |
Plugins extend gptme with custom tools and hooks (gptme plugin docs). See plugins/README.md.
| Plugin | Description |
|---|---|
| gptme-ace | ACE-inspired context optimization — hybrid retrieval, semantic matching, context curation |
| gptme-action-receipts | Append-only hashed audit ledger for tool actions |
| gptme-attention-tracker | Attention routing + history tracking for context management |
| gptme-claude-code | Claude Code subagent integration |
| gptme-consortium | Multi-model consensus decision-making |
| gptme-gptodo | gptodo delegation plugin for coordinator-only agent mode |
| gptme-gupp | Work persistence for session continuity |
| gptme-headroom-compressor | Lossless compression of tool outputs to reclaim context headroom |
| gptme-hooks-examples | Example hook implementations |
| gptme-imagen | Multi-provider image generation |
| gptme-lsp | Language Server Protocol integration for code intelligence |
| gptme-ralph | Ralph Loop pattern — iterative execution with context reset |
| gptme-retrieval | Automatic context retrieval via semantic/keyword search |
| gptme-tooloutput-trimmer | Read-time trimming of stale tool outputs |
| gptme-tts | Text-to-speech with local Kokoro models |
| gptme-user-memories | Automatic user-fact extraction across sessions — local ChatGPT-style memory |
| gptme-warpgrep | Enhanced search with Warp-style filtering |
| gptme-wrapped | Year-end analytics for your gptme usage (Spotify Wrapped-style) |
| gptme-youtube | YouTube transcript extraction and summarization |
Add to your gptme.toml:
[plugins]
paths = ["path/to/gptme-contrib/plugins"]
enabled = ["gptme_attention_tracker", "gptme_imagen"]Reusable Python packages, installable individually. See packages/README.md.
| Package | Description |
|---|---|
| aw-watcher-agent | ActivityWatch watcher for AI coding assistants (gptme, Claude Code, Codex) |
| bobutils | Shared workspace utilities for gptme agents (stdlib-only) |
| credential-slots | Safe credential-slot rotation for agents running Claude Max / OAuth-backed subscriptions |
| gptmail | Email automation for gptme agents with shared communication utilities |
| gptme-activity-summary | Activity summarization for gptme agents — journals, GitHub, sessions, tweets, email |
| gptme-backoff | Thin retry utilities built on tenacity — exponential backoff, jitter, and convenient async/sync decorators for agent tool calls |
| gptme-block-registry | Shared state-dir block-file contract and registry for gptme agent arm dispatch (credential-survival sublayer) |
| gptme-bob-status | Bob-specific StatusProvider for gptme-util status |
| gptme-body-protocol | Versioned, transport-neutral wire models for gptme body nodes |
| gptme-browser-semantic | Semantic browser primitives (observe/act/extract) for gptme computer-use — Path A: ARIA-snapshot scoring over gptme |
| gptme-cc-memory | Typed, git-tracked, hook-injected session memory for Claude Code — memory types, retention scoring, behavioral correction semantics, and prompt injection |
| gptme-codegraph | Structural code retrieval for gptme via tree-sitter (callers, callees, blast radius) |
| gptme-contrib-lib | Shared library code for gptme agents |
| gptme-coordination | Generic inter-agent coordination via SQLite: work claims, message bus |
| gptme-daily-briefing | Generic daily-briefing bundle schema and collectors for gptme agents |
| gptme-dashboard | Static dashboard generator for gptme workspaces |
| gptme-forum | Git-native agent forum (agentboard) — threaded posts, @mentions, and direct messages for gptme agents |
| gptme-lessons-extras | Lesson format validation and analysis |
| gptme-lessons-mcp | MCP server that exposes gptme |
| gptme-rag | ChromaDB-based RAG (Retrieval-Augmented Generation) for gptme agents |
| gptme-runloops | Python-based run loop framework for autonomous AI agent operation |
| gptme-sessions | Session tracking and analytics for gptme agents |
| gptme-subscription | Generic subscription observation, pressure scoring, and capacity-aware routing for agent credential slots |
| gptme-usage | Cross-backend usage, cost, and quota surface for gptme agents (model registry, cost math, quota checks) |
| gptme-vision-node | Vision pipeline for the BobBrain presence node — frame capture, person/motion detection, LLM look tool, and place recognition |
| gptme-voice | Voice interface for gptme with OpenAI and xAI Grok Realtime APIs |
| gptme-voice-node | Embedded voice presence node for BobBrain — thin WS client to bob-voice-server |
| gptme-whatsapp | WhatsApp integration for gptme agents via whatsapp-web.js |
| gptme-wisdom | Wisdom layer — BM25-searchable index of canonical reference books for gptme agents |
| gptme-wisdom-mcp | RAG-as-MCP Knowledge Server for gptme agents — search CS books and session history via MCP |
| gptodo | Task management and work queue generation utilities for gptme agents |
Standalone scripts and integrations — see scripts/README.md for the full index. Highlights:
| Area | Scripts |
|---|---|
| Context | context/ — agent system prompt generation |
| GitHub | github/, github_hygiene/, github_resolver/ |
| Social & messaging | discord/, telegram/, twitter/, bluesky/ |
| Issue tracking | linear/ |
| Research | autoresearch/, exa.py, perplexity.py |
| Health & quota | status/, check-quota.py, fleet_vitals.py |
| Safety | agent-write-loss-scan.py, workspace_validator/, git/ |
- skills/ — Skill bundles (workflows + scripts + docs): agent onboarding, plugin development, code review, artifact publishing, Home Assistant, and more. See skills/README.md.
- lessons/ — Shared lessons injected into agent prompts by keyword match, across categories (autonomous, communication, infrastructure, patterns, social, tools, workflow). See lessons/README.md.
- dotfiles/ — Global git hooks and config for safer agent development workflows. See dotfiles/README.md.
- docs/ — Plugin deep-dives and cross-agent protocols (e.g. the heartbeat protocol).
Beyond core, the template, and this repo:
| Project | Description |
|---|---|
| gptme-howto | Copy-paste recipes for gptme |
| gptme-plugin-registry | Central registry for gptme plugins — metadata, indexing, discovery |
| gptme-lessons | Agent network protocol — shared lessons across forked agents |
| gptme.vim | Vim plugin for gptme |
| gptme-cc-plugin | Claude Code skills for gptme — /gptme:run, /gptme:review, /gptme:context |
| gptme-skills-cc | Proven gptme agent skills packaged as a Claude Code plugin |
| agent-workspace-plugin | Claude Code plugin: persistent agent workspace (tasks, journal, lessons, knowledge) |
Archived: gptme-rag (upstreamed into packages/gptme-rag), gptme-webui, gptme-tauri.
Looking for a good place to start? The gptme.org Skills Gallery curates a handful of battle-tested skills from this registry with install commands and social proof — a quick one-page picker instead of reading the full index below.
To make your own plugin or skill discoverable, add a GitHub topic to your repo:
| Topic | For | Browse |
|---|---|---|
gptme-plugin |
Python plugin packages | ↗ |
gptme-skill |
SKILL.md skill bundles | ↗ |
gptme-mcp-server |
MCP servers for gptme | ↗ |
gh repo edit owner/your-repo --add-topic gptme-pluginFor a contributor checkout, start with Git, Python, and pipx
installed. Individual packages may require a newer Python version than the workspace
root; uv can download a compatible interpreter. If you already have uv on your
PATH, skip the pipx steps.
# Required for scripts with uv run shebangs
pipx install uv
pipx ensurepath
# If ensurepath changed PATH, open a new terminal before continuing.
# Run workspace commands inside a checkout, not an empty agent directory.
git clone https://github.com/gptme/gptme-contrib.git
cd gptme-contrib
# Install all workspace packages and plugins into a local .venv.
uv sync --all-packages
# Verify a contributed CLI starts without configuring an API key.
uv run --no-sync gptodo --helpThe full workspace includes large dependencies (for example, CPU PyTorch). For just one capability, use its linked package or plugin README instead of installing the entire workspace. Installing a plugin does not enable it in your agent; follow that plugin's configuration instructions.
See CONTRIBUTING.md for guidelines on contributing new tools, plugins, or lessons.
Plugins and packages here are community-contributed and may not be as mature or stable as core gptme functionality. They're a great place to experiment and share!
MIT License - feel free to use and modify as you like!