A morphlet is a structured, declarative specification — like a recipe — that describes a specific set of code changes to be applied to a codebase.
Morphlets are designed to be AI-readable and human-auditable. They provide the data and instructions required for an AI coding agent to apply consistent, context-aware changes across a codebase.
Each morphlet captures the intent, scope, and exact transformation steps needed to evolve a codebase — such as modifying configuration, refactoring logic, or updating styles — in a reusable, version-aware format.
Importantly, a morphlet is not the tool or actor that performs the transformation. It is the input to such a tool — a standalone unit of change that tells an AI agent what to do and why, without being tied to any particular implementation.
Sometimes it is not enough or possible to maintain or apply a code patch/diff to introduce a change in a codebase. In the pre-AI era, we used to store code snippets in gists or text files, and then would selectively copy-paste parts of them into the codebase, adjusting them to fit the context. This was error-prone, time-consuming, and hard to maintain. It would also be hard to share such changes with others.
In the AI era, we can do better. Morphlets are a way to formalize this process and make it more structured, reusable, and AI-friendly.
Morphlets allow you to maintain your own library of recorded changes as Markdown files that can be smartly and flexibly applied to a codebase by AI agents or humans.
Morphlets provide a format for describing changes and tools to apply them, making it easier to evolve codebases over time without losing track of what was done, why, and how.
This repository provides the Morphlet specification, tools, and examples to help you create, apply, and maintain morphlets in your projects.
We also provide a template for creating new morphlets, as well as capture and apply instructions for using morphlets with AI agents.
We automatically test the template and instructions with AI agents to make sure that the instructions are clear and actionable.
- AI-readable and human-auditable specifications for code changes
- Structured, declarative format using Markdown
- Version-aware and context-aware transformations
- Reusable morphlets that can be applied across different projects
- Template-based creation and standardized application process
- Built-in validation and verification steps
- Copy the morphlet template to your project
- Copy MORPHLET_CAPTURE.md or MORPHLET_APPLY.md depending on your needs
- Use with your AI agent following the instructions in the copied files
You can create and apply morphlets.
- Copy the morphlet template to a new file in your project.
- Copy MORPHLET_CAPTURE.md file to your project.
- Prompt your AI agent:
Read MORPHLET_CAPTURE.md and fill in <your morphlet file>.
By default, the agent will capture the changes in the codebase either for uncommitted files or for the last commit.
- Copy MORPHLET_APPLY.md file to your project.
- Prompt your AI agent:
Read the instructions in MORPHLET_APPLY.md and apply the changes described in <your morphlet file> to my codebase.
By default, the agent will apply the morphlet changes to the codebase. No code will be committed or pushed automatically.
Head over to the examples directory to see some morphlets.
Similar to how you maintain patches in your codebase, you can maintain
morphlets in a dedicated directory in your project. We suggest creating a
morphlets/ directory in the root of your project to store all morphlets.
Applied morphlets will have a date it was applied and validation checks filled in for each document.
The morphlet spec will be evolving over time, so you may need to update your morphlets to keep them compatible with the latest version of the morphlet spec. We will provide a migration guide for each morphlet version update.
MIT License - see LICENSE file for details.
This repository was created using the Scaffold project template
