gptme-contrib
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.
Where this fits in the gptme ecosystem
| 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.
Assembling a full agent
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
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 |
Plugin Usage
Add to your gptme.toml:
[plugins]
paths = ["path/to/gptme-contrib/plugins"]
enabled = ["gptme_attention_tracker", "gptme_imagen"]
Packages
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 OAuth/subscription-backed agents |
| gptmail | Universal email + inter-agent SSH messaging for agents |
| gptme-activity-summary | Activity summarization — journals, GitHub, sessions, tweets, email |
| gptme-backoff | Retry utilities: exponential backoff, jitter, async/sync decorators |
| gptme-bob-status | Bob-specific StatusProvider for gptme-util status |
| gptme-body-protocol | Neutral versioned wire DTOs for body-node clients and servers |
| gptme-cc-memory | Typed, git-tracked, hook-injected session memory for Claude Code |
| gptme-codegraph | Structural code retrieval with tree-sitter (call graph, blast/impact analysis, MCP tools) |
| gptme-contrib-lib | Shared utilities |
| gptme-coordination | Inter-agent coordination via SQLite: work claims, message bus |
| gptme-daily-briefing | Daily briefing generation for agents |
| gptme-dashboard | Static dashboard generator for agent workspaces |
| gptme-forum | Git-native agent forum — threaded posts, @mentions, DMs |
| gptme-lessons-extras | Lesson validation and tools |
| gptme-lessons-mcp | MCP server exposing gptme's lesson matching to any MCP client |
| gptme-rag | Local RAG with ChromaDB — semantic search as CLI, gptme tool, or MCP server |
| gptme-runloops | Run loop framework for autonomous agent operation |
| gptme-sessions | Session tracking, analytics, and trajectory extraction |
| gptme-subscription | Subscription observation, pressure scoring, capacity-aware routing |
| gptme-usage | Cross-backend usage, cost, and quota surface (model registry, cost math) |
| gptme-voice | Real-time voice interface via OpenAI and xAI Grok Realtime APIs |
| gptme-whatsapp | WhatsApp integration via whatsapp-web.js |
| gptme-wisdom | BM25-searchable index of canonical reference books |
| gptme-wisdom-mcp | RAG-as-MCP knowledge server — search books and session history |
| gptodo | Task management CLI and work queue generation |
Scripts
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, Lessons & More
- 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).
Ecosystem
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.
Discover more
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-plugin
Dependencies
Some scripts require additional dependencies:
# Required for scripts with uv run shebangs
pipx install uv
# Install all packages
uv sync --all-packages
Contributing
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!
License
MIT License - feel free to use and modify as you like!