The problem
Vibe coding makes software creation feel more accessible—until a beginner meets words like API, server, database, token, MCP, authentication, and deployment all at once.
A capable coding agent can usually produce working code, but its explanation may still assume the mental model of an experienced developer. Beginners then face a frustrating choice: interrupt the build to research every term, or continue without understanding what they are approving.
Fairytail adds a small, opt-in teaching layer to coding agents:
Minimal code, maximal clarity.
It keeps the host agent's normal workflow intact, stays quiet on routine work, and activates richer guidance only when the user asks for a beginner-friendly explanation, an analogy, personalization, or an initial-system design walkthrough.
What Fairytail does
Fairytail is an installable plugin for Codex CLI and Claude Code that provides:
- beginner-friendly explanations for foundational agent-development concepts;
- reviewed English and Korean renderings from shared canonical facts;
- concrete analogies with an explicit “where the analogy breaks” section;
- a private, user-authored local profile for more familiar examples;
- semantic, quiet-by-default activation instead of an always-on keyword injector;
- bounded output and deterministic fallback behavior;
- additive integration beside existing harnesses such as Superpowers, oh-my-opencode, and oh-my-codex.
A bare question such as What is an API? intentionally stays on the host's
normal answer path.
A request such as:
I am designing my first app. Explain how an API, a server, and a database work together using one familiar analogy.
can activate Fairytail's richer concept layer and return a connected mental model: what each component is, how data moves between them, what beginners commonly confuse, and where the analogy stops being accurate.
Why it is different
Many assistant add-ons compete to orchestrate more tools, agents, and context. Fairytail focuses on a narrower missing layer: helping a person understand the system being built without making every interaction longer.
The implementation and explanation lanes are deliberately separated:
ordinary question or trivial edit ───────────────► host default path
explicit non-trivial build request ─► minimal-build policy
└─► smallest safe implementation
beginner / analogy / initial-design intent ─► Fairytail concept skill
├─ reviewed facts
├─ local profile, if approved
├─ EN or KO presentation
└─ bounded final explanation
Fairytail does not replace Codex, control its permissions, or rewrite a
project's AGENTS.md. The host still owns planning, tools, execution, and
completion judgment.
Personalization without profiling
We did not create a fixed list of personas such as “student,” “doctor,” or “designer.”
During optional onboarding, the user answers five local questions about their language, preferred explanation style, familiar worlds, current goal, and concepts they already understand. Those user-authored answers become the source of truth.
The profile is stored locally with private file permissions. Raw answers do not need to enter the model conversation. Fairytail only reuses a validated analogy mapping after the user has approved it. If no safe mapping exists, it falls back to a reviewed generic analogy instead of guessing a profession or personal trait.
Users can also choose neutral explanations or disable analogies entirely.
How we built it
The plugin has four main layers:
- Semantic selection
Skill metadata describes when the rich explanation is appropriate and, just
as importantly, when it is not. Fairytail does not install a
UserPromptSubmit keyword classifier or inject context into every prompt.
- Canonical concept content
English is the source language for reviewed facts and relationships. Korean is a reviewed presentation locale. Both share the same concept IDs, safety boundaries, and analogy breakpoints.
- Private profile and analogy binding
A local profile stores only user-authored preferences. Optional personalization fills tightly constrained noun-role slots; validation rejects mappings that change the underlying technical facts.
- Deterministic bounded renderer
Once selected, the direct concept path reads bundled content and produces the final explanation locally. It exposes no model client, network client, command runner, or repository-search step.
The current release reviews ten concept families, including APIs, servers, databases, MCP, tokens, permissions, repositories, packages, environments, and deployment.
Built with Codex and GPT-5.6
Codex was the primary engineering environment for repository analysis, implementation, test design, public-install verification, documentation, privacy review, and release preparation.
During OpenAI Build Week, a persistent GPT-5.6 Sol Codex session was also used to inspect the real repository and challenge the product boundary: the best judge experience should demonstrate the existing deterministic renderer instead of adding a new runtime or inflating the plugin.
That collaboration reinforced the core design decision: use the frontier model where reasoning and review are valuable, while keeping repeated beginner explanations small, inspectable, and deterministic.
Challenges we faced
Activating at the right moment
The first challenge was not generating more explanation—it was avoiding unnecessary explanation. Keyword-heavy activation was too brittle, while always-on context would penalize every task. We moved the decision into narrow semantic skill descriptions and tested both positive and negative intents.
Being personal without inventing a persona
A few seed personas cannot represent real users. The profile therefore had to remain user-authored, optional, private, and revocable, with generic reviewed behavior when personalization is incomplete.
Proving clarity without misleading metrics
Longer output is not automatically clearer, and fewer tokens are not automatically better. We separated hard engineering invariants from claims that require human research. We report bounded payloads, routing observations, and structural coverage, but we do not claim a completed human-comprehension study.
Validation
The current public release passes the following bounded checks:
- 52/52 direct renders across 26 aliases and two locales;
- 48 balanced English/Korean intent fixtures covering rich and default routes;
- 10/10 reviewed generic analogy families in each locale;
- 30/30 personalized role-mapping validation fixtures;
- 7/7 steps in a disposable Codex beginner onboarding journey;
- maximum observed single-concept payload of 1,013 bytes;
- a three-concept initial-design bundle of 2,718 bytes;
- 0 model, 0 network, and 0 execution calls inside the deterministic renderer.
These are reproducible engineering checks, not a claim that every beginner will prefer every explanation. A consented human comprehension pilot is still future work.
What we are proud of
Fairytail can be useful without taking over the host.
It gives a beginner a richer explanation when needed, yet preserves the fast native path for routine questions and implementation. It works in English and Korean, installs from a public GitHub marketplace, keeps profile data local, and can coexist with larger coding-agent harnesses.
The result is not a second coding agent. It is a small translation layer between expert software concepts and the person trying to build their first real system.
Try it
codex plugin marketplace add ernestolee13/fairytail
codex plugin add fairytail@fairytail
codex plugin list --json
Start a new Codex thread, then run:
$fairytail:doctor Diagnose my setup without showing profile answers.
$fairytail:onboard Set up my profile in Korean.
$fairytail:fairytail-explain-concept Explain MCP in Korean with a beginner-friendly analogy and its limit.
Source, setup, architecture, privacy boundaries, and reproducible evidence are available in the public GitHub repository.
What's next
Next we want to run a consented novice study, expand reviewed concept coverage, improve locale-specific analogy quality, and add more host integrations without weakening the quiet-by-default boundary.
Log in or sign up for Devpost to join the conversation.