Public Plugin Private Overlay
The standard for agent plugins (Claude Code and similar): one public, generic plugin; everything about the user in a private overlay folder; a private workspace repo for the work. How to build one, and how to convert a private plugin.
About This Project
Public-Plugin-Private-Overlay provides a structural standard for building AI agent plugins, such as those for Claude Code, by isolating user-specific data into a private overlay folder. This approach ensures that generic plugin code remains public and maintainable, while personal configurations, secrets, and environment-specific settings are kept private and persistent across plugin updates. It eliminates the need for parallel private forks, which often suffer from version drift and maintenance overhead.
The project implements a three-part architecture consisting of the plugin itself, a user-specific overlay for settings and templates, and a private workspace repository for project-specific output. By utilizing environment variables for secret management and following a strict lookup order for configuration files, it allows developers to distribute functional, generic tools that remain highly customizable for individual users. This methodology is particularly useful for developers and power users who want to share agent capabilities without compromising private credentials or complex local workflows.