KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

patchmd

★ 40 Open GitHub ↗

An open format for declarative, AI-native code transformations.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# patch.md

**An open format for declarative, AI-native code transformations.**

A `patch.md` is a markdown file that describes a change in natural language — versioned in git, authored in any text editor, applied by any LLM-based agent. The format is the primitive; registries, marketplaces, and tooling are downstream of the convention.

patch.md has two modes:

- **Source-tree patches** edit a codebase you own — your app, your package, your mod's source. Specified in [RFC 0001](./rfc/0001-patch-md.md).
- **Overlay patches** inject behavior into a running host you don't own — a website you visit, a deployed service, a game you play. Specified in [RFC 0002](./rfc/0002-overlay-patches.md).

Both share the same document format, substitution rules, and `verify`-as-contract model. Status: early draft.

## The smallest valid patch.md

```markdown
# patch.md

## meta
- name: fix-typos

## files

### README.md (modify)
Fix any typos, grammatical errors, and awkward phrasing. Do not
change the meaning or structure of any section.
```

That's it. Two sections, one file operation.

## A more realistic patch.md

```markdown
# patch.md

## meta
- name: add-stripe-checkout
- version: 1.0.0
- target: next.js >= 16

## files

### src/lib/stripe.ts (create)
Create a Stripe client wrapper that exports a configured Stripe
instance using STRIPE_SECRET_KEY from environment variables.

### src/app/api/checkout/route.ts (create)
POST handler that creates a Stripe checkout session and returns
its URL as JSON.

## verify
- `src/lib/stripe.ts` exports a named `stripe` instance
- POST /api/checkout with a valid priceId returns 200 with a `url` field
```

See [`examples/`](./examples) for a spectrum of patches, from one-line notes-to-self to full publishable integrations.

## Why the format matters

Diffs are line-positional and brittle. Codemods are expensive to author and framework-coupled. Developers already describe changes to agents in natural language every day — there's just no shared format for it.

patch.md is a minimal markdown convention that is human-writable, model-agnostic, and verifiable through a behavioral-contract section (`## verify`). The full motivation and spec live in [RFC 0001](./rfc/0001-patch-md.md).

## Repository layout

- [`rfc/`](./rfc) — numbered design documents for the format and ecosystem
  - [`0001-patch-md.md`](./rfc/0001-patch-md.md) — source-tree patches (filesystem)
  - [`0002-overlay-patches.md`](./rfc/0002-overlay-patches.md) — overlay patches (runtime injection into hosts you don't own)
- [`examples/`](./examples) — illustrative `patch.md` files spanning both modes and the specificity spectrum
- [`skills/`](./skills) — Anthropic-format skills for agents that interpret or apply `patch.md` files

## Contributing

This repo is the home base for the format — spec, RFCs, and examples. Tooling and reference executors will live in separate repos. Open an issue or PR to propose changes to the spec.

## Acknowledgments

Inspired by [Theo Browne (t3dotgg)](https://github.com/t3dotgg). Prior art includes [SOUL.md](https://soul.md) (markdown convention for agent personas) and Anthropic's [SKILL.md](https://www.anthropic.com/engineering/skills) format.

patchmd

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README