home / lessons
Lessons from great codebases
I read one open-source codebase cover to cover, then write up eight things it does better than most. Every claim links to the code.
Every round, I read one open-source codebase cover to cover: the server, the clients, the lint rules, the CI, the PR templates, even the bot configs. Then I write up eight things it does better than most projects. Every repo I pick is one I'd hold up as an example of good engineering.
How each lesson works
- In short: the problem and the idea, in two sentences, at the top.
- The engineering: how the repo actually does it, with real code, numbers and quotes from its docs. Some lessons have a live demo you can poke at.
- Steal this: the idea in one paragraph you can take to your own code.
- Use it in your code: a prompt you paste into your coding agent. It checks whether the idea fits your repo before it changes anything.
- Read the source: links to the exact files the lesson is based on, so you can check my work.
Each codebase ends with power-user tips for actually using the tool.
OpenCode (new)
anomalyco/opencode, the open-source coding agent (these lessons are from its upcoming v2). A durable prompt inbox, a system prompt that never gets rewritten, bounded tool output, compaction before overflow, and more, from a rewrite still in progress.
- 1 · ArchitectureAdmit the prompt first, run it later2 minA durable inbox between “you pressed Enter” and “the model sees it.”
- 2 · PerformanceNever rewrite the system prompt2 minFreeze the baseline, append what changed, and keep the provider cache warm.
- 3 · TestingRecord real HTTP once, replay it forever2 minCassettes instead of mocks, and a CI that refuses to record.
- 4 · Context engineeringBound what the model sees3 minOne size limit per tool result: keep the head and the tail, save the rest to a file.
- 5 · API designOne API, even in-process2 minThe embedded SDK sends real requests to the real router, without a network.
- 6 · Dev processRebuild on the main branch2 minA new major version grown next to the old one, with a dated log of every contract change.
- 7 · SecurityConfigured is not allowed2 minPolicy is its own layer, and the last matching rule wins.
- 8 · AI-native engineeringCompact before you overflow3 minSummarize old turns before the request stops fitting, keep recent ones word for word.
- tips20 power-user tips5 minThe TUI, custom commands, permissions and headless runs, checked against its docs.
Pi
earendil-works/pi, the minimal, extensible agent harness. A core that lets you replace its own features, import budgets, append-only session trees, an edit tool built for sloppy models, and more.
- 1 · ArchitectureShip a small core, and make your own features replaceable2 minIts MCP support is a plugin, and a third-party plugin can replace it. That's the point.
- 2 · PerformanceEntry points are cost contracts2 minImporting one 6 KB function loaded 106 files. Now a commit check counts them.
- 3 · TestingA fake model and an empty environment2 minAgent tests with no real models, no real keys, and nothing from your machine.
- 4 · Data modelNever mutate history3 minSessions as an append-only tree: branches, summaries and even edits are new entries.
- 5 · SecurityTreat the lockfile as code2 minThree packages may run install scripts. Every other dependency change has to ask.
- 6 · Agent toolsDesign a tool a model can't misuse3 minExact match first, fuzzy match second, loud errors, and one queue per file.
- 7 · UI / UXDecide who owns the scrollback2 minTwo terminal renderers, one interface, and a test that counts full redraws.
- 8 · AI-native engineeringMeasure whether your docs help2 minRun the agent with and without the docs, and keep what moves the number.
- tips20 power-user tips5 minShortcuts, extensions and workflow tricks for the terminal agent harness.
T3 Code
pingdotgg/t3code, the open-source GUI for coding agents. Architecture, performance budgets as tests, testing without sleeps, a PR process for the AI era, lint rules as taste, and more.
- 1 · ArchitectureDecide, commit, then act2 minThe three-step server pattern that keeps AI agents from leaving your app in a weird state.
- 2 · PerformancePerformance budgets belong in unit tests2 minSeven performance patterns from one repo's commit log, and why their budgets fail the build.
- 3 · TestingMock the boundary, not the logic2 min“A test that needs a timeout to pass is wrong.” Testing rules from a repo that bans sleeps.
- 4 · GitHub & PRsA PR process for the AI era2 minWhen anyone can generate a 2,000-line PR in ten minutes, review time is what you protect.
- 5 · DX & ToolingTurn taste into lint rules1 minReview comments don't scale. A repo with 14 custom lint rules shows what does.
- 6 · Dev setupA dev setup built for ten agents on one laptop2 minPorts, databases, processes and URLs: everything shared becomes a collision once agents run in parallel.
- 7 · UI / UXLying spinners, stale labels, one-way doors2 minUX rules from a repo whose users stare at it all day and notice every lie the UI tells.
- 8 · AI-native engineeringWrite docs for your most frequent contributor1 minIn this repo, the most frequent contributor is an AI agent running inside the app itself.
- tips30 power-user tips5 minKeyboard shortcuts, remote environments and workflow tricks, from using it every day.