Keep Claude's harness buffed.
Patina is the compounding retro loop for Claude Code that layers every session, near-miss, and team agreement into PATINA.md: an AI constitution owned by the whole team, polished one cycle at a time. It minimizes context bloat, instruction drift and staleness, while maintaining the most important agreements and guardrails.
Things only humans witness.
Near-misses, frustrations, team agreements – context your codebase can never explain to an agent. patina capture logs them while they're fresh.
Synthesised, not averaged.
Each teammate runs patina reflect on their own machine before the retro to capture their perspective. patina run weaves all of it into a new layer.
Nothing lands without review.
Claude proposes one concrete diff. A human reads it, approves it, commits it. The file stays 50 lines (or 500 tokens) max. Trimming is as common as adding.
to first value — just run patina init and patina run to get started
less back-and-forth re-explaining conventions the agent already agreed to last sprint
optimized core for machine inference, proactive bloat alerts
every layer is reevaluated continuously, preventing model and context drift
A feedback loop that actually sticks.
Anyone can capture. Everyone reflects. One person runs the synthesis and commits the update. The next session picks up the change automatically, for everyone.
patina capture
Record a notable moment while it's fresh. UUID-named JSON — no merge conflicts.
$ patina capture --tag near-miss "almost pushed to main" ✓ captured
patina reflect
Answer the questions your team picked. Async. Every voice lands in the shared data dir.
$ patina reflect
how did this cycle feel?
what went well?
✔ answers saved patina run
Claude ingests logs, captures, and reflections and applies the next layer.
$ patina run ✔ 12 sessions · 5 captures ✔ updated PATINA.md
Use the Claude Skill /patina to run the commands from within Claude Code sessions.
Watch the layers build.
Each retro cycle, Claude proposes a change to your shared Patina. It optimises for quality and machine inference. Trimming is as common as adding, so the file stays tight.
Foundation — onboarding cycle
Top 3 rework patterns identified
Token discipline working; rework dropping
Approval gates added after near-miss
Context creep surfaced early; pre-flight rule added
Run patina layers in your project to see your last 5 cycles and their improvements.
Loaded into every session through CLAUDE.md.
Core always loaded, spokes on demand: detailed autonomy scenarios, incident logs, and cycle history give deeper context when needed.
the whole team.
versioned in git.
Not a report. Not a draft.
Patina is the record.
/insights disappears when the session ends. CLAUDE.md rots while nobody's watching. However, PATINA.md compounds. Every retro adds one deliberate layer, based on the previous layer and the whole team's learnings.
| /insights | CLAUDE.md | PATINA.md | |
|---|---|---|---|
| Lives in | your machine | your repo | your repo |
| Owned by | you alone | whoever last edited | the whole team |
| Based on | all your previous sessions | some outdated best practice | project-specific sessions and your team's learnings |
| Tailored to | you | the project | your team |
| Evolves with use | one-off, doesn't persist | decays silently | one deliberate layer per retro |
| Changes reviewed | N/A | sometimes | always |
| Loaded into sessions | no | yes | yes |
| Stays small | N/A | grows unbounded | 500 token limit, spokes on demand |
First layer deposited in ten minutes.
Free. MIT licensed. Node 18+. Uses your existing Claude Code auth, no separate API key needed. If you don't have the CLI, set ANTHROPIC_API_KEY and Patina falls back to the SDK.
$ npm install -g @lcvbeek/patina $ cd your-project $ patina init # scaffolds .patina/ $ patina run # onboarding on first run $ git commit -m "first patina layer"
Any questions?
What's a harness and why does it need maintenance? +
As Vivek Trivedi puts it: "if you're not the model, you're the harness." System prompts, tool definitions, approval gates, skills, MCPs, orchestration, working agreements — everything around the model that turns it into an agent.
Models ship every few months; your harness doesn't update itself. Two things go wrong when no one tends it. First, capability gets absorbed: guardrails and workarounds written for an older model's failure modes turn into dead weight the next model has to work around. Second, the harness overfits — tool descriptions, prompts, and constraints quietly get shaped to one model's quirks, and a new release exposes the mismatch as regressions.
Patina is the maintenance loop. Each cycle it reads your session logs, surfaces what's actually tripping the agent up, and proposes a reviewed edit to PATINA.md — so the harness keeps pace with the model instead of fossilizing around it.