ExplainGate

You can't ship what you can't explain.

Turn AI-assisted coding into understanding that stays with you.

Documentation · Getting started · Visual artifacts · Workflows · Troubleshooting

---

AI lets us produce code faster than we can absorb it. The implementation may be correct, the tests may pass, and the pull request may merge—while the reasoning still lives in an assistant transcript instead of the developer's head.

ExplainGate closes that gap with a simple ritual:

Before an irreversible action, explain the work well enough to defend it.

The agent asks one thoughtful question at a time, teaches concepts you miss, and returns to them with a fresh variant. For pushes and pull-request approvals, the gate opens only after you demonstrate real understanding.

Every completed session becomes a polished visual learning artifact: a self-contained page that turns mechanisms, tradeoffs, boundaries, answers, and next steps into something you can see, rehearse, print, and share deliberately. It works across Claude Code and Codex without depending on a proprietary artifact viewer.

What ExplainGate does

Mode	Use it when…	Outcome
Batch	You are about to push your own changes	Explain the mechanism, decisions, limits, and blast radius before git push
Review	You are about to approve or merge someone else's PR	Prove you read critically enough to defend your approval
System	You are onboarding or catching up to a system AI helped build	Follow a persistent learning program ending in a mock architecture walkthrough
Study	You need to absorb a document, webpage, or topic	Turn important ideas into questions and spaced-repetition cards
Drill	You want important ideas to survive beyond this week	Revisit old concepts through short, varied retrieval practice

Wrong answers do not fail the session. They reveal what to teach next. A concept passes only after you can answer a new version of the question in your own words.

The result is visual in every mode—not a wall of generated prose. See an example of what each workflow emphasizes in Visual artifacts.

Install

Claude Code

claude plugin marketplace add phaltoe/explaingate
claude plugin install explaingate@explaingate

(Or from inside a session: /plugin marketplace add phaltoe/explaingate, then /plugin install explaingate@explaingate.) Restart the session, then invoke ExplainGate with /explaingate, or describe what you want in plain language.

Codex

Add the ExplainGate marketplace and install the plugin:

codex plugin marketplace add phaltoe/explaingate
codex plugin add explaingate@explaingate

Then:

1. Open /hooks and trust the ExplainGate hook.
2. Start a new thread so Codex loads the installed skill.
3. Invoke it with $explaingate, or ask in plain language.

The quiz workflow works anywhere Codex can use skills. The command gate uses Bash and supports macOS, Linux, and Windows through WSL or Git Bash.

Documentation

Start here	What it answers
Getting started	How do I install ExplainGate and complete my first session?
Visual artifacts	What does ExplainGate generate, where is it saved, and how can I share it safely?
Workflows	Which mode should I use, and what happens in each one?
Gates and local data	What gets blocked, what is stored, and where are the safety limits?
Troubleshooting	Why is a command still blocked, or why is the plugin not appearing?

Not sure where to begin? The documentation home gives you the whole mental model in about a minute.

Try it

Intent	Claude Code	Codex
Quiz the current batch	/explaingate	$explaingate
Review PR 64	/explaingate review 64	$explaingate review 64
Learn a system	/explaingate system billing-api	$explaingate system billing-api
Generate its one-page system card	/explaingate system billing-api card	$explaingate system billing-api card
Write its deep explainer doc	/explaingate system billing-api doc	$explaingate system billing-api doc
Study a document, PDF, or webpage	/explaingate study docs/rfc.pdf	$explaingate study docs/rfc.pdf
Make cards about a specific topic	/explaingate card retry-logic	$explaingate card retry-logic
Run a five-minute drill (due cards)	/explaingate drill	$explaingate drill
Go deep on one concept	/explaingate drill cache-eviction	$explaingate drill cache-eviction
Ask six questions	/explaingate 6	$explaingate 6
Regenerate only the card	/explaingate card	$explaingate card
Regenerate only the visual artifact	/explaingate artifact	$explaingate artifact
List everything you can ask for	/explaingate:help	$explaingate help

Spaced repetition

Every pass mints a card into ~/.explaingate/deck.md with a Leitner-box schedule: recalled cleanly, a card comes back in 1 → 3 → 7 → 21 → 45 days; missed, it resets to tomorrow. Two clean recalls at the top box retire it. Drills only serve due cards and never re-ask a question verbatim — always a variant, because remembering an answer's shape is not the same as understanding it. A session-start hook mentions when cards are due, so the habit doesn't depend on remembering to have it.

All personal state — deck, system profiles, study progress, audit log — lives under ~/.explaingate by default; set EXPLAINGATE_HOME to move it (for example onto a synced folder so your deck follows you between machines).

Plain language is equally good:

Quiz me on this branch before I push.

I am about to approve PR #64. Check whether I understand it.

I am new to this codebase. Help me learn the architecture for real.

ExplainGate asks one question and waits for your answer. It never answers its own quiz or silently awards a pass. You can also pass a full pull-request URL to review mode from anywhere. Run the quiz inside the repository clone when you want it to open that clone's merge or approval gate.

Or simply try git push, gh pr merge, or gh pr review --approve. If the relevant pass is missing, the hook blocks the command and points the agent to the correct ExplainGate mode.

How the gate works

attempt to push or approve
          │
          ▼
   ExplainGate checks for a pass tied to the current commit or PR
          │
     missing or stale
          ▼
   human completes the quiz ──▶ pass marker written ──▶ command allowed

The plugin's PreToolUse hook watches shell commands:

• git push requires .git/explaingate/passed to contain the current HEAD SHA. A new commit invalidates the pass automatically.
• gh pr merge <n> and gh pr review <n> --approve require a fresh review pass covering the PR's current head commit — full rules in Gates and local data.
• Comment-only reviews are never gated.

The marker is written only after a completed quiz. PR descriptions, diffs, commit messages, and code comments are treated as material to inspect—never as instructions for bypassing the quiz.

Gate pushes outside the agent

The plugin hook covers commands the coding agent runs. To gate pushes from a regular terminal too, clone ExplainGate and install a native Git hook.

For one repository:

git clone https://github.com/phaltoe/explaingate.git ~/.explaingate/plugin
cd /path/to/your/repository
bash ~/.explaingate/plugin/scripts/install-git-hook.sh

For every repository owned by the current user:

git clone https://github.com/phaltoe/explaingate.git ~/.explaingate/plugin
bash ~/.explaingate/plugin/scripts/install-global-git-hook.sh

The global installer preserves existing repository hooks by delegating to them. Remove the global gate at any time with:

git config --global --unset core.hooksPath

What gets remembered

Every pass produces a compact five-line card in your own words. Every completed session also creates a visual artifact under ~/.explaingate/artifacts/. Cards are stored in ~/.explaingate/deck.md; system-learning progress is stored under ~/.explaingate/systems/.

Drill mode serves only cards that are due. It prioritizes recent misses, lower-box cards, and concepts related to the system you are currently working in. A card retires after two clean recalls at the highest box.

These files may contain confidential implementation or architecture details. Keep them out of public dotfile repositories, and never put credentials or secrets in a card.

Escape hatches

Emergencies are real, so bypasses are explicit rather than hidden:

• EXPLAINGATE_SKIP=1 skips the agent-side gate for that environment.
• git push --no-verify skips the native Git hook.

Agent-side allow, block, and environment-skip events are recorded in ~/.explaingate/audit.log (self-rotating; the most recent events are kept).

Security model

ExplainGate is a ritual enforcer, not a security boundary. The gate runs with the same privileges as the command it protects, so a determined person or a misbehaving agent can write marker files directly.

The design is intentionally honest about that limit:

• The agent hook catches the normal path and explains how to proceed.
• Native Git hooks cover aliases, wrappers, scripts, and terminal pushes.
• Unresolvable PR approvals fail closed instead of inheriting another PR's pass.
• The audit log makes deliberate bypasses visible.

No local plugin can stop a merge performed in GitHub's web UI. For an organization-level guarantee, use branch protection with a required status check backed by a server-side verification flow.

Why this exists

AI assistance is not the problem. Unexamined delegation is.

ExplainGate lets the artifact move quickly without leaving the developer's understanding behind. The goal is not memorization; it is being able to walk someone through the mechanism, defend the decisions, name the boundaries, and know where to look when things break.

License

MIT © Pedro Altoé