Core Files

README.md

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
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
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

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

Lessons

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

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!

Packages (10)

Name	Version	Description
gptmail	0.1.0	Email automation for gptme agents with shared communication utilities	src
gptme-activity-summary	0.1.0	Activity summarization for gptme agents — journals, GitHub, sessions, tweets, email	src
gptme-contrib-lib	0.1.0	Shared library code for gptme agents	src
gptme-dashboard	0.1.0	Static dashboard generator for gptme workspaces	src
gptme-lessons-extras	0.1.0	Add your description here	src
gptme-runloops	0.1.0	Python-based run loop framework for autonomous AI agent operation	src
gptme-sessions	0.1.0	Session tracking and analytics for gptme agents	src
gptme-voice	0.1.0	Voice interface for gptme with OpenAI Realtime API	src
gptme-whatsapp	0.1.0	WhatsApp integration for gptme agents via whatsapp-web.js	src
gptodo	0.1.0	Task management and work queue generation utilities for gptme agents	src

Name

Version

Description

gptmail

0.1.0

Email automation for gptme agents with shared communication utilities

src

gptme-activity-summary

0.1.0

Activity summarization for gptme agents — journals, GitHub, sessions, tweets, email

src

gptme-contrib-lib

0.1.0

Shared library code for gptme agents

src

gptme-dashboard

0.1.0

Static dashboard generator for gptme workspaces

src

gptme-lessons-extras

0.1.0

Add your description here

src

gptme-runloops

0.1.0

Python-based run loop framework for autonomous AI agent operation

src

gptme-sessions

0.1.0

Session tracking and analytics for gptme agents

src

gptme-voice

0.1.0

Voice interface for gptme with OpenAI Realtime API

src

gptme-whatsapp

0.1.0

WhatsApp integration for gptme agents via whatsapp-web.js

src

gptodo

0.1.0

Task management and work queue generation utilities for gptme agents

src

Plugins (16)

Name	Description
gptme-ace	Context optimization plugin for gptme, providing hybrid retrieval, semantic matching, and context curation for the lesson system.	src
gptme-attention-tracker	Attention tracking and routing plugin for gptme. Combines two complementary tools for context optimization:	src
gptme-claude-code	Claude Code plugin for gptme - spawn Claude Code subagents for various coding tasks.	src
gptme-consortium	Multi-model consensus decision-making for gptme.	src
gptme-gptodo		src
gptme-gupp	Work persistence plugin for gptme - track work across session boundaries using the GUPP pattern.	src
gptme-hooks-examples	Purpose: Demonstrates how to create plugins with hooks that extend gptme's behavior at various lifecycle points.	src
gptme-imagen	Multi-provider image generation for gptme.	src
gptme-lsp	LSP (Language Server Protocol) integration plugin for gptme, providing code intelligence features like diagnostics, definitions, and references.	src
gptme-ralph	A gptme plugin implementing the Ralph Loop pattern - iterative execution with context reset between steps.	src
gptme-retrieval	Automatic context retrieval plugin for gptme.	src
gptme-tts	Text-to-speech (TTS) plugin for gptme using Kokoro.	src
gptme-user-memories	A gptme plugin that automatically extracts user facts from past conversations and stores them for inclusion in future sessions — like ChatGPT's "memory" feature but fully local.	src
gptme-warpgrep	Agentic code search plugin for gptme using [Morph's warp-grep](https://docs.morphllm.com/sdk/components/warp-grep/direct).	src
gptme-wrapped	Year-end analytics for your gptme usage - inspired by Spotify Wrapped.	src
gptme-youtube	YouTube transcript extraction and summarization plugin for [gptme](https://gptme.org).	src

Name

Description

Status

gptme-ace

Context optimization plugin for gptme, providing hybrid retrieval, semantic matching, and context curation for the lesson system.

src

gptme-attention-tracker

Attention tracking and routing plugin for gptme. Combines two complementary tools for context optimization:

src

gptme-claude-code

Claude Code plugin for gptme - spawn Claude Code subagents for various coding tasks.

src

gptme-consortium

Multi-model consensus decision-making for gptme.

src

gptme-gptodo

src

gptme-gupp

Work persistence plugin for gptme - track work across session boundaries using the GUPP pattern.

src

gptme-hooks-examples

Purpose: Demonstrates how to create plugins with hooks that extend gptme's behavior at various lifecycle points.

src

gptme-imagen

Multi-provider image generation for gptme.

src

gptme-lsp

LSP (Language Server Protocol) integration plugin for gptme, providing code intelligence features like diagnostics, definitions, and references.

src

gptme-ralph

A gptme plugin implementing the Ralph Loop pattern - iterative execution with context reset between steps.

src

gptme-retrieval

Automatic context retrieval plugin for gptme.

src

gptme-tts

Text-to-speech (TTS) plugin for gptme using Kokoro.

src

gptme-user-memories

A gptme plugin that automatically extracts user facts from past conversations and stores them for inclusion in future sessions — like ChatGPT's "memory" feature but fully local.

src

gptme-warpgrep

Agentic code search plugin for gptme using [Morph's warp-grep](https://docs.morphllm.com/sdk/components/warp-grep/direct).

src

gptme-wrapped

Year-end analytics for your gptme usage - inspired by Spotify Wrapped.

src

gptme-youtube

YouTube transcript extraction and summarization plugin for [gptme](https://gptme.org).

src

Lessons & Skills (102)

Reference catalog — autonomous (17), communication (3), concepts (4), patterns (10), skill (7), social (1), tools (23), workflow (37)

Title	Kind	Category	Status	Keywords
ACE (Agentic Context Engineering)	lesson	concepts	archived	agentic context engineeringACE contextliving playbookscontext window optimization strategydynamically curate LLM context	src
Add New Package Paths to mypy Configuration	lesson	tools	active	mypy Can't find package errornew workspace package mypy failuremypy_path missing new packagetype checking fails after adding packageadd package to mypy.ini	src
Agent Credential Management	lesson	workflow	active	manage API keysOAuth blocked at passwordAPI key for agent workspacestore credentials in .envsecret rotation for agent	src
Agent Event Watch Workflow	lesson	autonomous	active	event watchwatch tasksettlement watchupcoming eventscheduled result	src
Agent Event Watch Workflow	lesson	workflow	active	event watchwatch tasksettlement watchtrigger datestandup result	src
Agent Orchestrator Patterns	lesson	workflow	active	orchestrating multiple agentsagent team health checkdaily agent standupinference utilization across agentsmonitor agent work queue	src
Agent Visual Identity Establishment	lesson	patterns	archived	visual identityavatarbrand identityagent brandingvisual representation	src
Agent Workspace Maintenance	lesson	workflow	active	updating gptme-contrib submoduleverify workspace symlinksagent workspace maintenanceworkspace symlink verificationupdate submodule to latest	src
Agent Workspace Setup	lesson	workflow	archived	setting up new agent workspaceinitialize gptme agent from templatenew agent from gptme-agent-template	src
Always Branch From Remote Master	lesson	workflow	active	create branchgit checkout -bnew feature branchPR contains unrelated commits	src
Always Use Absolute Paths for Workspace Files	lesson	workflow	active	save file towrite journal entrymkdir -p journalfile pathwrong directory	src
Autonomous Operation Safety	lesson	autonomous	active	lethal trifectaprivate datauntrusted contentexternal communicationprompt injection	src
Autonomous Session Pivot Strategies	lesson	autonomous	active	pivot when blockedswitch tasks when stuckalternative value-creationtechnical issues blocking workautonomous session pivot	src
Autonomous Session Structure	lesson	autonomous	active	autonomous session structure4-phase sessionsession phase planningstructured autonomous sessionautonomous work phases	src
Avoid Deeply Nested Code Structures	lesson	patterns	active	deep nesting 4+ levelsnested if statement pyramidguard clause patternearly return for simplicityfunction extraction for nesting	src
Avoid Excessive Setup When Testing Components	lesson	patterns	active	spending too much time on setup5+ chains on prerequisitesneed to understand full pipeline before testingexcessive setup before testing componentuse mock data instead of full pipeline	src
Avoid Long Try/Catch Blocks	lesson	patterns	active	try block too longexception handling > 10 linessplit error handling into focused blocksmultiple operations in one try blockgeneric error messages	src
Blocked Period Status Check Trap	lesson	autonomous	active	blocked periodstatus checkrepetitive commitsall tasks blockedstatus check trap	src
Bold Refactoring	lesson	workflow	active	adding new code without refactoringproposing refactoring without doing itshared module created but not usedPR adds code without removing oldrefactor when adding abstraction	src
Browser Verification for Web Changes	lesson	tools	active	verify web changes in browsercheck browser console errorsdeployment verificationcommit web changes without testingpush without browser check	src
CI Failure Resolution and Pre-commit Infrastructure Maintenance	lesson	workflow	active	multiple consecutive CI failures on masterrestore corrupted pre-commit scriptsprek run failing with persistent errorsCI status red on master branch	src
Check CLI --help Before Reading Source Code	lesson	tools	active	examine source code to understand CLIplanning complex workaroundmaking assumptions about CLI optionsunfamiliar command usagediscover CLI flags and options	src
Check for Existing PRs Before Creating	lesson	workflow	active	about to create PRgh pr creategit checkout -b fix-gh pr list --searchissue has been open for a while	src
Clean PR Creation	lesson	workflow	active	messy PRunrelated commitsclean PRcherry-pick commitsPR hygiene	src
Close the Loop	lesson	patterns	active	reduce human intervention in autonomous workflowsmake agents more autonomousautomate the feedback loopautonomous long-running tasksminimize human touchpoints	src
Code Coverage Principle	lesson	workflow	archived	add teststest coveragewrite tests forpytest coveragemissing tests	src
Communication Loop Closure Patterns	lesson	workflow	active	close the loopreply to issue commentupdate the requestorsilent work completionmemory failure response	src
Configure pytest pythonpath for Monorepo	lesson	tools	active	pytest ModuleNotFoundErrortests fail to importpytest pythonpathworkspace package not foundcannot import in tests	src
Cross-Agent Workspace Review	lesson	workflow	active	cross-agent reviewworkspace review patternsreviewing other agent's workmutual workspace analysiscross-agent knowledge sharing	src
Data Loader PR Quality Patterns	lesson	patterns	active	data loadercsv loaderfile not foundassert pathmissing file test	src
Detect and Break Repetitive Action Loops	lesson	patterns	active	posting same comment multiple times in loopagent stuck in endless retry cyclerepeating failed action without progressdetected repetitive tool calls	src
Documentation Principle	lesson	workflow	active	let me document thisworth documentingcreate a knowledge articleupdate the knowledge basedocument the finding	src
Effective Autonomous Work Execution	lesson	autonomous	active	start of autonomous sessionautonomous work workflowtask selection in autonomoussession startup workflowselect what to work on	src
Escalation vs Autonomy Decision Framework	lesson	autonomous	active	should I ask the user or proceed autonomouslyuncertain whether to escalate or decideneed human review before proceedingrisky action requiring approvalirreversible change decision point	src
Fork PR Secrets Access	lesson	workflow	active	CI secret not availablefork PR failing CIsecret not accessible via forkpush directly to repoANTHROPIC_API_KEY not set	src
GEPA-Based Lesson Optimization	lesson	concepts	active	gepa-lesson-optimizergepa mutation runlesson mutation with gepagenetic-pareto lesson optimizationapply gepa to lessons	src
Git Commit Message Format	lesson	workflow	active	conventional commitscommit message formatwrite commit messagecommit type prefixfeat fix docs commit	src
Git Workflow	lesson	workflow	active	never use git add . or git commit -astage only intended files explicitlycommit trivial docs directly to masteraccidental staging of unintended filessubmodule update sequence	src
Git Worktree Workflow for External Repositories	lesson	workflow	active	git worktreeworktreesubmit PR to externalPR to gptmebranch from origin/master	src
GitHub Comment Formatting for File References	lesson	communication	active	github comment formattingfile reference linkclickable file linkgithub file referenceformat file paths in comments	src
GitHub Issue Follow-Through Pattern	lesson	communication	active	issue follow-throughclose communication looprespond after completingconfirm completion in threadmissing follow-up response	src
GitHub Issue and PR Engagement	lesson	social	active	github issueopen issuecreate issueclose issueabout to create new issue	src
Hierarchical Context Management (Droid Architecture)	lesson	concepts	active	context window managementorganize context across stepsprune older conversation contextlayered context approachcontext accumulating across steps	src
Inter-Agent Communication	lesson	workflow	active	inter-agent communicationagent-to-agent messagingcross-agent coordinationcommunicate with other agentmessage another agent	src
LLMLingua (Compression Technique)	lesson	concepts	active	compressionllmlinguatoken pruningprompt compressiontext compression	src
Lesson Quality Standards	lesson	autonomous	active	knowledge base bloatlesson bloatknowledge capturelesson creationlesson quality	src
Linear API Integration	lesson	tools	active	query Linear issueslinear-activity.pyLINEAR_API_KEY not setLinear GraphQL mutationcreate Linear ticket	src
Maintaining Readiness During Blocked Periods	lesson	autonomous	active	maintaining readiness when blockedproductive while waitingblocked period activitiesall tasks blockedstrategic pause framework	src
Making Progress Despite Blockers	lesson	workflow	active	PR queue overloadedmultiple PRs awaiting reviewall tasks waiting on reviewnothing to do while waitingeverything blocked on external	src
Markdown Codeblock Syntax	lesson	tools	active	file content getting cut off mid-codeblockfiles ending with incomplete contentcodeblock without language tag causing parse errorssave operation truncating contentunclosed code block	src
Match mypy Error Codes to Actual Error Type	lesson	tools	active	type: ignoremypy import errorimport-not-foundimport-untypedCannot find implementation or library stub	src
Measure Before Optimize	lesson	workflow	active	implementing optimization without profilingassuming slowness based on complexitybuilding caching before confirming problemsthis looks complex so it must be slowpytest --profile	src
Memory Failure Prevention	lesson	workflow	active	memory failurecommunication loopsduplicate workcontext losssession handoff	src
Multi-Issue Coordination Patterns	lesson	autonomous	active	multiple tasks blockedall work waiting for reviewblocked across multiple issuesparallel blocked taskscoordinate blocked work	src
Notion MCP Integration	lesson	tools	active	notionnotion mcpnotion integrationnotion apinotion token	src
PR Recovery After Accidental Closure	lesson	workflow	active	pr recoveryclosed praccidental closurereopen prforce-push closed	src
Persist Before Noting	lesson	patterns	active	noted for future referenceI'll remember thiswill keep this in mindgood to know for next timelearned this for future	src
Pre-Issue Creation Checklist	lesson	workflow	active	duplicate preventionissue creationpre-action checkmemory failurework verification	src
Pre-Landing Self-Review	lesson	workflow	active	self-reviewpre-landingreview iterationcode reviewsubstantial change	src
Pre-Mortem for Risky Actions	lesson	autonomous	active	about to delete or remove filesforce push or destructive git operationmodifying production infrastructurerisk assessment before actionwhat could go wrong with this change	src
Proactive Correction in Agent Messages	lesson	workflow	active	retract incorrect recommendationsent wrong advice to agentneed to correct prior messageearlier message was wrong	src
Progressive Disclosure for Documentation	lesson	patterns	active	documentation file consuming excessive context tokensalways-included file over 500 linescontext budget consumed by rarely-needed contentmonolithic documentation needs restructuringrestructure large documentation	src
Project Monitoring Session Patterns	lesson	workflow	active	structured monitoring triage workflowACT vs DEF notification classificationmonitoring session derailing into investigationmulti-project notification triage	src
Python File Execution	lesson	tools	active	python script permission deniedbash: script.py: Permission deniedchoose correct python execution methodshebang python executionModuleNotFoundError when dependencies should be available	src
Python Invocation	lesson	tools	active	bash: python: command not foundpython command not founduse python3 instead of pythonpython vs python3which python to use	src
Read Full GitHub Context	lesson	workflow	active	truncating github comment outputrespond to stale context when conversation evolvedread entire issue thread before respondingmissing newer comments that supersede earliergh pr view --comments \| head	src
Read PR Reviews Comprehensively	lesson	workflow	active	read ALL review sources without truncationreply to individual review comment threadsbatch all review replies in one shell blockmaintainer says you didn't address review commentsunresolved review threads on PR	src
Requirement Validation Before Implementation	lesson	workflow	active	WHO requested this featureWHAT problem does this solvevalidate before implementingseems like a good idea without requesterbuilding before validating need	src
Responding to Code Review Feedback	lesson	communication	active	code review feedbackpull request reviewmaintainer feedbackrespond to reviewreview comments	src
Rule-Driven Session Gating for Monitoring Agents	lesson	autonomous	active	inference costmonitoring sessionssession gatingno-op sessionsskip session	src
Run uv sync --all-packages After Workspace Changes	lesson	tools	active	ModuleNotFoundError workspace packagepackage not installed despite pyproject.tomluv workspace package missingcannot import workspace package after addinguv sync all packages after changes	src
Safe Operation Patterns	lesson	autonomous	active	classify operation before executingsafe to execute autonomouslyrequires human approvaloperation safety classificationrisky operation	src
Scope Discipline in Autonomous Work	lesson	autonomous	active	while working on X noticed Y could be improveddiscovered tangential improvement opportunityalso fixed some nearby code while at itscope creep during autonomous sessionstaying focused on stated objective	src
Session Ending Protocol	lesson	workflow	active	session endingland the planesession completefinish sessionending session	src
Session Startup Recent Actions Review	lesson	workflow	active	skipped recent actions reviewmissed previous session contextincomplete communication loopduplicate work from missing contextcontext gap from last session	src
Shell Command Chaining	lesson	tools	active	environment variable lost between blocksshell blocks lose contextchain shell commandscommand chainingvariable not found in second block	src
Shell Output Filtering for Token Efficiency	lesson	tools	active	filter output with grep head tailcommand dumped 10k+ tokenslarge output 1000+ linestoken efficiency shell	src
Shell Path Quoting for Spaces	lesson	tools	active	path with spacesquoted pathspaces quotingcd: too many argumentstoo many arguments	src
Sibling Tool Call Errored Cascades from One Failed Tool in a Batch	lesson	tools	active	sibling tool call erroredparallel tool call failedtool call error in batch	src
Simplify Before Optimize	lesson	patterns	active	optimize performanceadd cachingspeed upmake it fasterimprove efficiency	src
Stage Files with git add Before Commit/prek	lesson	tools	active	pathspec did not matchnothing added to commitStashing unstagedprek shows old errorscommit untracked file	src
Stated Intention Follow-Through	lesson	workflow	active	i'll doi willfollow throughaccountabilityintention	src
Strategic Completion Leverage When Blocked	lesson	autonomous	archived	blocked on externalwaiting for stakeholderexternal dependencies blockingstrategic value creationstrategic completion leverage	src
Strategic Focus During Autonomous Sessions	lesson	autonomous	active	strategic focus disciplineproductivity trap avoidancedarwinian trap avoidanceautonomous session planningstrategic work selection	src
Thompson Sampling for Work Category Optimization	lesson	autonomous	active	implement thompson sampling for work categoriesbandit over work categoriesoptimizing session mode banditcategory selection explore exploitwork category bandit setup	src
Tmux for Long-Running Processes	lesson	tools	active	process killed at 120 secondsshell timeout exceededtmux for long-running processprocess runs longer than 2 minutes120-second shell timeout	src
Todoist MCP Integration	lesson	tools	active	todoisttodoist mcptodoist integrationtodoist apitodoist token	src
Triggering Greptile PR Reviews	lesson	tools	active	trigger greptile re-review after improvementsPR received low quality score from greptilevalidate quality improvements before human review@greptileai review comment@greptileai	src
Using ast-grep for Code Refactoring	lesson	tools	active	sg run --patternast-grep structural searchcode refactoring across filesreplace pattern in codebaseAST-based code transformation	src
Verifiable Tasks Principle	lesson	workflow	active	how do I know when this is doneno way to verifyunclear completion criteriatask success is unclear	src
When to Rebase PRs	lesson	workflow	active	commits behind⟳ behind⚠ CONFLICTSmergeable=falserebase based on behind count	src
gh pr checks --watch Exits 8 for Pending Checks (Not a Failure)	lesson	tools	active	exit code 8gh pr checks watch pendingchecks still pendingpr checks not complete	src
gh-pr-review Extension for Review Thread Management	lesson	tools	active	resolve review threadresolve review commentreview threadsgh-pr-reviewclose conversation thread	src
gptme-contrib Contribution Pattern	lesson	workflow	active	contribute lessoncontrib PRexternal contributionsubmit lessonupstream lesson	src
mcp-cli for Token-Efficient MCP Interactions	lesson	tools	active	mcp-climcp cliMCP tokenMCP contextlazy MCP	src
Gptme Wrapped	skill	skill	active		src
Plugin Development	skill	skill	active		src
agent-onboarding	skill	skill	active		src
artifact-publishing	skill	skill	active		src
code-review-helper	skill	skill	active		src
progressive-disclosure	skill	skill	active		src
template-skill	skill	skill	active		src

Title

Kind

gptme-contrib workspace

Session Stats

Activity

Recent Sessions

Services

Schedule

Service Health

Service Logs

Recent Journal Entries

Core Files

gptme-contrib

Overview

Plugins

Plugin Usage

Packages

Scripts

Lessons

Dependencies

Contributing

License

Packages (10)

Plugins (16)

Lessons & Skills (102)