gptme-contrib

Community-contributed plugins, packages, scripts, and lessons for gptme.

Overview

This repository contains:

• plugins/ - Extend gptme with custom functionality (gptme docs)
• packages/ - Reusable Python packages
• scripts/ - Standalone scripts for automation
• commands/ - Thin command-catalog entries for runtime procedure discovery
• lessons/ - Shared lessons for prompts and workflows

Plugins

Plugins extend gptme's capabilities with custom tools and hooks. See plugins/README.md for details.

Plugin	Description
gptme-ace	ACE-inspired context optimization
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-hooks-examples	Example hook implementations
gptme-imagen	Multi-provider image generation
gptme-lsp	Language Server Protocol integration
gptme-ralph	Ralph Loop pattern — iterative execution with context reset
gptme-retrieval	Automatic context retrieval via semantic/keyword search
gptme-warpgrep	Enhanced search with Warp-style filtering
gptme-wrapped	Year-end analytics for your gptme usage (Spotify Wrapped-style)

Plugin Usage

Add to your gptme.toml:

[plugins]
paths = ["path/to/gptme-contrib/plugins"]
enabled = ["gptme_attention_tracker", "gptme_imagen"]

Packages

Reusable Python packages. See packages/README.md.

Package	Description
gptme-codegraph	Structural code retrieval with tree-sitter (parse, call graph, blast/impact analysis, 9 MCP tools)
gptmail	Universal email system for AI agents
gptodo	Task management CLI and utilities
gptme-activity-summary	Activity summarization for agents — journals, GitHub, sessions, tweets, email
gptme-sessions	Session tracking, analytics, and trajectory extraction
gptme-voice	Voice interface using OpenAI Realtime API
gptme-whatsapp	WhatsApp integration for agents via whatsapp-web.js
gptme_lessons_extras	Lesson validation and tools
gptme_runloops	Agent run loop patterns
gptme_contrib_lib	Shared utilities
gptme-forum	Git-native agent forum — threaded posts, @mentions, and DMs
gptme-subscription	Subscription observation, pressure scoring, and capacity-aware routing
gptme-daily-briefing	Daily briefing generation for agents
gptme-dashboard	Agent usage dashboards and metrics

Scripts

Standalone scripts for automation. See each directory's README for details.

Directory	Description
context/	Context generation for agent system prompts
discord/	Discord bot integration
github/	GitHub context generation, repo status
linear/	Linear issue tracking integration
telegram/	Telegram bot integration
twitter/	Twitter automation and monitoring
bluesky/	Bluesky integration
status/	Agent infrastructure status monitoring
workspace_validator/	Agent workspace structure validation

agent-write-loss-scan

Detects the write-loss (git-clobber) hazard in gptme agent sessions: a session writes to a file inside a git-tracked workspace, but the change is silently reverted before it is ever committed — the write is lost without any error.

Why this matters: Autonomous agents write, but multi-session hot-windows can revert those writes via git stash/restore/checkout -- operations. Measured write-loss rates in production: 0.051% overall, up to 0.68% for memory files.

Usage:

# Basic scan (human-readable)
python3 scripts/agent-write-loss-scan.py --repo /path/to/workspace

# JSON output for programmatic use
python3 scripts/agent-write-loss-scan.py --repo /path/to/workspace --json

# Filter by date, limit session count
python3 scripts/agent-write-loss-scan.py --repo /path/to/workspace \
  --since 2025-01-01 --limit 50

Output fields (JSON):

{
  "total_writes": 142,
  "persisted": 138,
  "superseded": 2,
  "lost": 2,
  "unknown": 0,
  "loss_rate": 0.0141,
  "loss_pct": "1.4%",
  "events": [...]
}

Classification:

Outcome	Meaning
PERSISTED	Written content was committed to git
SUPERSEDED	A later commit changed the file to different content (not a loss)
LOST	File reverted to pre-write state; content was never committed
UNKNOWN	Untracked path or ambiguous git history

The scanner is strictly read-only: it never runs git stash, checkout, reset, or restore — only git log, cat-file, and ls-files.

Lessons

Shared lessons provide reusable prompts and workflow patterns. See lessons/README.md.

Ecosystem

gptme has a broader ecosystem of standalone repos beyond gptme-contrib.

External Projects

Project	Description	Status
gptme-rag	Local RAG — semantic document search as a CLI or gptme tool	Active
gptme-tauri	Desktop app built with Tauri	Archived
gptme-webui	Web UI for gptme	Archived

Discover More

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!