Learn by Building
You build. AI writes.
A Codex plugin that puts learning first and keeps you in control while AI writes the code you designed. Codex asks for your approach first, helps you examine tradeoffs, and explains unfamiliar concepts. You shape the design and decide when it's ready to implement. Codex writes the code, then explains what it changed and why.
For anyone who wants to learn as they build—whether you're an aspiring engineer, a junior developer, or an experienced engineer exploring an unfamiliar stack. Practice planning how the pieces fit together, anticipating failures, and checking the result while keeping ownership of the decisions.
Get started
Full Codex port of VibeWise by Noah Kim, pinned to upstream c5fc8d8 (0.1.43). The teaching guides, hooks, reset helper, examples, and tests are retained with host-specific adaptations. See NOTICE.md.
You need Python 3 and a Codex environment supporting skills. Automatic restoration additionally requires trusted lifecycle hooks and locally available scripts.
Standalone skills
In a Codex environment with the skill installer, request both skills:
$skill-installer install https://github.com/aroraanushri/learn-by-building/tree/main/skills/learn-by-building
$skill-installer install https://github.com/aroraanushri/learn-by-building/tree/main/skills/reset-learning
Invoke $learn-by-building to start or resume and $reset-learning to preview a reset. In ChatGPT use the installed skill picker or @mentions. These are skill names, not guaranteed slash commands.
Standalone skills include the full teaching and reset workflows but do not register hooks. Invoke Learn explicitly in a new session to restore context.
Full local plugin
Clone this repository and install its root plugin.json through your Codex client's supported local plugin installation workflow. It declares hooks/hooks.json; skills are under skills/. This project is not listed in the public plugin directory. Current OpenAI docs limit hook-containing plugins to manual local installation.
Review and trust the hook in Codex before enabling it. Installation alone does not trust hooks. The command uses python3; if unavailable on your platform, change it to your Python 3 interpreter in your local hook definition and review the changed definition again.
The hook matches SessionStart sources startup/resume/clear/compact. It requests restoration only for a project with active notes; installing does not activate learning everywhere. It reads the activation marker and emits instructions pointing to the guides and notes. Codex then reads them. The hook never edits notes.
Official references: Codex hooks, plugin packaging.
Setup asks one question at a time using native preference choices where available and text otherwise. Use defaults skips customization. For an existing repository, Codex inspects the code and sketches an evidence-based system map.
What it feels like
You're building a Notion-style notes app: users sign in, create and edit private notes, and organize them into folders. Here, you're working through how notes and folders relate—and what should happen when someone deletes a folder.
This condensed example is adapted from a real learning session. Later implementation steps are illustrative; intervening design discussions are omitted.
You:
A note can be in several folders. Deleting a folder should delete its notes.
Codex:
✦ Build checkpoint: Deleting a shared note
"Trip ideas" is in both Travel and Summer. Deleting it removes it from both.
When someone deletes Travel, what should happen to that note in Summer?
You:
Keep it in Summer. If it has no folders left, keep the note outside any folder.
Codex:
That separates deleting a folder from deleting a note.
✦ Build checkpoint: Connecting notes and folders
How would you represent which folders a note belongs to, without copying the note?
You:
A links table with note_id and folder_id. Deleting a folder removes its links,
not the notes.
Codex:
Each link records one membership. Several links can point to the same note;
a note with no links is unfiled.
notes ← folder links → folders
✦ Design checkpoint: Folder membership
Proposed: store notes once and track folder membership in a links table.
Deleting a folder removes its links and keeps the notes. This supports multiple
folders per note; loading a folder's notes needs a lookup through those links.
Confirming records this design. We still need to work through access rules
and technology choices before writing code.
❯ 1. Confirm and continue
This approach makes sense to me; move to the next piece.
2. Discuss
Ask questions or clarify anything that doesn't make sense before deciding.
You:
Confirm and continue.
Later, after the remaining choices for this step are worked through...
Codex:
✦ Implementation checkpoint: Folder membership
I'll add the agreed tables and folder-deletion operation, then test that deleting
a folder preserves its notes and their membership in other folders.
This step builds storage behavior; the UI comes later.
❯ 1. Implement this step
This approach makes sense to me; write the code for this step.
2. Discuss
Ask questions or clarify anything that doesn't make sense before deciding.
You:
Implement this step.
Codex writes the code and runs the tests.
Codex:
✦ Implementation report: Folder membership
- Added the schema migration: each membership references one note and one folder.
- Added folder deletion: removes the folder and its links, preserving note content.
- Added and ran tests for shared notes and notes left without a folder; both passed.
You don't need to know the answer already. Codex can explain unfamiliar concepts, sketch the relevant pieces, and help you tackle a smaller question. You stay involved in forming the plan. Answer in plain English; ask for more help or say “skip” whenever you want.
Describing what you want sets the requirements. Build Checkpoints ask you to work out how it should function; a feature preference doesn't approve an architecture.
| Checkpoint | What happens |
|---|---|
| Build | You reason through how to approach the problem with Codex. |
| Design | Review the design. Confirm and continue records it and continues planning; no code yet. |
| Implementation | Review the specific code changes. Implement this step authorizes Codex to make them. |
These aren't three mandatory stops. When ready to code, the Implementation checkpoint also confirms the design, skipping a separate Design checkpoint. Both confirmations offer Discuss to ask questions, clarify anything confusing, or explore alternatives before deciding.
When Codex proposes additional implementation details, it separates them from your decisions in a short list or table explaining each addition and why it matters. You can question or change any item before proceeding.
After implementation, Codex briefly explains what changed, how the key code works, why it fits your decision, any tests it added or updated and what they cover, and which checks ran with their results. Ask to dig deeper anywhere it's unclear.
Small diagrams help you trace data, understand relationships, and see how the system fits together.
Make it yours
Experience changes the support you get, not your ownership of decisions:
| Level | Teaching approach |
|---|---|
| Beginner | Explain unfamiliar pieces, use diagrams, ask smaller reasoning questions. |
| Intermediate | Less introductory context; explore interactions and tradeoffs. |
| Advanced | Probe difficult constraints, failure modes, and design assumptions. |
Everyone reasons first. Codex adapts to what you demonstrate and how familiar you are with the stack. Checkpoint frequency—Light, Normal, or Frequent—is separate.
- “Use fewer checkpoints.”
- “Focus on backend architecture.”
- “Use multiple-choice questions.”
- “Just implement this one.”
- “Pause learning.” Resume with
$learn-by-building.
Preferences, learning notes, and a project map live in .learn-by-building/ in your project. With the full local plugin installed and its hook trusted, restoration is requested in future sessions and after compaction. Standalone skills require explicit invocation. Add .learn-by-building/ to your .gitignore to keep your notes out of Git; the plugin won't change it silently.
No extra account, backend, or telemetry. Saved notes are included in Codex's context, so your normal Codex data settings still apply.
To start learning this project from scratch, run $reset-learning. It shows the
project and asks Cancel / Reset learning. After confirmation, it backs up your
profile, progress, and project map inside the notes directory's backups/ folder,
then restarts onboarding. Source code and other projects stay untouched. To change
your experience level or preferences, just tell Codex; no reset is needed.
Updating
Pull new files and update your installed skills or local plugin through your client's supported workflow. Changed hook definitions require renewed review and trust. Updates do not reset project notes.
Compatibility and validation
Includes the complete teaching workflow, onboarding, checkpoint types, experience levels, preferences, notes, project maps, pause/resume, and preview/confirmation reset with backups.
Native picker appearance and local plugin installation UI depend on the Codex surface. Anthropic Directory installation and Claude marketplace commands are not Codex commands.
Automated tests execute the hook and reset helper in temporary projects. They cover lifecycle event payloads, note lookup, large histories, paused mode, symlinks, backups, stale confirmations, and failure recovery. They do not prove live Codex event delivery or native UI behavior. See development notes.
License
MIT. You can use, modify, and share this software, including commercially. Keep the license notice with copies. The software comes without a warranty.