Keeping a mental map of a codebase takes deliberate work when a coding agent can introduce changes faster than you can explore them. I built Code Bearings to give that exploration some structure: short quizzes about how the code fits together, with explanations and source evidence after each answer.
I spent a couple of days recently vibe coding it, and I've now made it public. I've found it useful for revisiting changes to my applications, and it also supports something familiar to anyone who has helped a new engineer get oriented: working through a repository together and talking about how it behaves.
Understanding AI-generated code takes practice
When I work in a repository, I want a mental model I can use to reason about the next change. That means understanding where a responsibility belongs and following the path from an action to its result. Reading an explanation helps; trying to answer a question gives me a reason to test that understanding against the source.
That was the idea behind Code Bearings. Give an engineer a bounded set of questions about a repository or a committed change, then put the relevant code beside the explanation so they can follow the connection for themselves.
The focus is on relationships and behavior within the project you're exploring. Questions about how data moves through the system or how responsibilities are divided between components help you reason about what a change will affect.
What a Code Bearings session looks like
The viewer runs locally in your browser and opens a prepared quiz file. You can work through it alone, or one person can share the browser during a team call and use the questions to start a discussion.
You answer a question, then reveal the result. The viewer shows the explanation and lets you explore the supporting source excerpts, with filenames and original line numbers. Those references stay hidden until the reveal, so you get a chance to reason through the question first. You can also choose “I'm not sure” and go straight to learning from the explanation.
The included example uses Code Bearings' own source. One question asks where answer comparison and result rendering belong. Its explanation connects src/core/session.js, which computes the outcome, to the viewer's presentation code. That gives the discussion a concrete boundary to examine: which behavior belongs in the core, and which belongs in the interface?
The example contains 10 questions, including single-choice, multiple-select, and ordering questions. It targets 25 minutes including discussion (a planning target rather than a measured completion time). Each answer has correctness feedback, and the session ends with a learning recap that collects topics to revisit.
How quizzes are prepared and checked
Code Bearings separates preparation from the learning session. A skill runs in a coding agent, reads committed source, and creates a portable .quiz.json package. I've tested preparation with Codex and Claude Code, using their support for independent subagents.
A separate verifier first solves the questions from source before seeing the answer key. It then reviews the complete package, checking the explanations and evidence as well as the answers. The preparation process requires that independent check before it treats a quiz as ready to play.
Each package records the repository URL, branch, and full commit SHA. A quiz about a change set records its base commit too, so claims about what changed have a specific range behind them. Source excerpts travel inside the file; participants can follow the evidence during a session even when they haven't cloned the repository.
That verification is still an agent's review, and it deserves the same judgment you'd apply to other AI-assisted work. The embedded excerpts make the reasoning inspectable, and the recorded revision gives you a way to open the surrounding code when a question needs a closer look.
How to try Code Bearings
The v0.1.0 early preview release includes a prebuilt viewer, the preparation skill, and the example quiz. The download instructions cover running the viewer through a local web server and installing the skill. The example is a useful place to start because it lets you experience the question and reveal flow before preparing anything yourself.
To make a quiz for your own repository, install the whole exported skill folder and start a fresh coding-agent session in that repository. Preparation requires Node.js 22.12 or newer, Git, and a coding agent with independent subagent support. Invoke $code-bearings-quiz in Codex or /code-bearings-quiz in Claude Code, then give it a request such as:
Prepare a repository overview for newcomers using this branch's committed tip.
Target 25 minutes including discussion. Save it to ~/quizzes/.
You can also request a change-set quiz for a feature branch or a merged commit. That scope is useful when you're already familiar with the application and want to spend the session on what a particular piece of work introduced.
Open the resulting .quiz.json file in the viewer to play it. Once the viewer has loaded, an imported quiz works offline, and playback needs no model-provider API keys. Answers and progress last for the current browser session. Packages from private repositories contain source excerpts, so keep those files and their preparation records in a private destination.
What I'd like to learn from this preview
Code Bearings is free under the MIT license, and this release is an unsupported early preview. I've found a use for it in my own work; broader usability and learning effectiveness still need evidence from people trying it in their own settings.
If you try it, I'd be interested in which questions helped you understand a connection in the code and where an explanation left you wanting more context. You can report a Code Bearings issue with a minimal fictional example, or join the conversation on my LinkedIn launch post. The part I'm interested in is what happens after the answer appears, when you follow the source and the code starts to fit together.