ExplainIT

A plain-English twin for every code file, and a human checkpoint in front of every change your AI coding assistant makes. Local only. Uses the assistants you already have. Ships no model, holds no keys, runs no server, sends no telemetry.

ExplainIT does two things and does them completely:

1. Explains. When you open a code file, a second file with the same name plus _explain (app.py → app_explain.txt) opens beside it. It lists every function in numbered order and describes each one in a few short, simple sentences anyone can understand. The twin is a real text file next to your code, but it is never committed or pushed.
2. Checks. When Claude Code or Codex tries to change code, the change is stopped before it reaches the disk. The file opens, you see exactly what is changing — one function at a time — next to a fresh plain-English note saying what changed and why it matters. Only when you click Accept does the change land; then the twin is updated to match, and only then may the assistant continue. Reject sends your reason straight back to the assistant so it can revise.

Everything runs on your own machine. The explanations are written by the assistants you already have connected and pay for.

How the checkpoint works, per assistant

Whatever the path, every change ExplainIT sees is written to a tamper-evident local journal, a restore point is saved first, and you can restore any file with one click.

What is sent where

• Your code goes only to the assistants you already use, under your existing agreements. To write an explanation, ExplainIT sends the function body (and, at most, a short file summary — never whole files in thrift mode) to the assistant you picked: Copilot through VS Code's language-model API, Claude Code through claude -p, or Codex through codex exec.
• Nothing goes to us. There is no ExplainIT backend, account or server. The extension makes no network calls of its own. Its only network activity is a loopback (127.0.0.1) connection between the hook scripts and the extension in the same machine.
• No telemetry. None. Logs stay in an Output channel and a rolling file under ~/.explainit/logs.
• No keys. ExplainIT stores no API keys and no credentials. Your assistants sign in the way they already do.

Setup

1. Install ExplainIT from the Marketplace (or Open VSX for VSCodium and Cursor).
2. Have at least one assistant installed and signed in: Claude Code (terminal tool or the VS Code extension), Codex (terminal tool or the VS Code extension), or GitHub Copilot.
3. On first use ExplainIT asks your permission to use those assistants. Choose Allow. (Run ExplainIT: Set up assistants at any time to see this screen again.)
4. ExplainIT detects what you have — Copilot in VS Code, Claude Code, Codex, including the VS Code extensions and the binaries they bundle — and offers a one-click Connect for each. Connecting installs the checkpoint hook and tells you the remaining steps: restart the assistant, and for Codex do the trust step once.
5. Codex trust step. Codex only runs hooks you have trusted. Open codex once in a terminal; when it shows the ExplainIT hook, choose Trust (or type /hooks and trust it there). The Codex VS Code extension shares that trust record, so you do this once, not per window. Until then Codex changes are not stopped for review, and the Doctor says so ("Codex trusts the ExplainIT hook").
6. If nothing is found you get the three install links and a Check again button.
7. Open any code file. The twin opens beside it. Run ExplainIT: Doctor whenever you want proof that everything is installed, armed and healthy.

The twin format

ExplainIT — plain-English twin of app.py
Written by ExplainIT. Not committed to git. Right-click a section for "Regenerate this section".

1. load_config
What it does: Reads the settings file and turns it into a settings object.
How it works:
- It opens the file at the given path.
- It reads all of the text.
- It turns the text into a settings object.
- It hands the object back.

2. Server.start
What it does: Starts the web server so it can answer requests.
How it works:
- It picks the port from the settings.
- It begins listening on that port.
- It logs that it is ready.

Only functions that are new or changed are ever sent to an assistant; unchanged functions are served from a local content-hash cache so your credits are not wasted. When a function changes and its section has not been regenerated yet, the line (Out of date — the code changed. Right-click here and choose "ExplainIT: Regenerate this section".) appears under its heading.

Settings

Commands

All commands live under the ExplainIT category in the Command Palette.

When something goes wrong

Five short runbooks cover the most likely problems, each with symptoms, cause and fix steps:

1. No assistant found
2. The checkpoint is not stopping changes — restart the assistant, the Codex trust step, the hooks layer, the Doctor
3. The twin is not opening — auto-open off, unsupported file type, language not outlined, big files
4. ExplainIT is not responding — the fallback within two minutes explained, how to recover
5. Restore a file, or the journal fails to verify

Codex sign-in. If the Doctor or an explanation reports refresh token was revoked or Please log out and sign in again, Codex's sign-in has expired. Run codex login in a terminal (the Codex VS Code extension uses the same sign-in), then try again. ExplainIT adds this hint to the message whenever Codex answers that way.

Codex trust. If the Doctor's "Codex trusts the ExplainIT hook" check is a problem, its text is the adapter's own verdict: not trusted yet, changed since it was trusted, disabled, or "Trust unknown — run the Doctor after starting codex once". None of these can be fixed by Fix all: open codex once in a terminal and choose Trust (or type /hooks), then run the Doctor again. If you set CODEX_HOME, ExplainIT reads and shows that location instead of ~/.codex.

The status bar shows $(shield) ExplainIT while the checkpoint is alive, turns red with not responding if no heartbeat arrives for 15 seconds, and shows ExplainIT paused while the kill switch is on. Every empty, loading and error state has a plain-English message that says what happened and what to do next.

Privacy and security

• Loopback only. The checkpoint listens on 127.0.0.1 on a random port per window, with a random per-session bearer token that is never logged. Hook payloads are schema-validated, paths are canonicalised (symlinks resolved) and confined to your open folders, and request size is capped.
• Protected paths. Assistants cannot switch the checkpoint off: writes to ~/.explainit/** (hook scripts, wrappers, sessions, state, journal, restore points), to the hook entries in ~/.claude/settings*.json and ~/.codex/hooks.json / config.toml (or their $CODEX_HOME equivalents), to .git/info/exclude, and to .git/hooks/** and .git/config (git runs those as you, outside ExplainIT) are refused outright with a reason. Writes elsewhere under .git/ are handed to the assistant's own prompt with a warning. Shell commands are read the same way: cd/pushd into a protected folder followed by a redirect, tee or heredoc is refused whatever explainit.checkpoint.shellWrites says.
• Pinned locations. The hook command installed in the assistants' settings carries the absolute ExplainIT home and config locations, and the wrappers export them before running the hook, so changing EXPLAINIT_HOME, HOME or CODEX_HOME in a shell profile cannot point the hook at a rogue checkpoint or move the protected files. The command text is part of the integrity hash.
• Integrity. The hook script, wrappers and config entries are hashed and verified every session and by the Doctor; tampering is re-armed automatically. The Doctor's live wiring test runs the real installed wrapper, the same way the assistants do.
• Prompt-injection defence. Code being explained is fenced as untrusted data with a fixed never-follow-instructions rule; twin output is plain text, schema-validated, never executed, and never influences a gate decision. A twin an assistant writes itself is re-rendered by ExplainIT from its own cache once the write lands, and the journal says so.
• Decision memory is short-lived. "Accept the rest of this file/session" is keyed on the session the assistant reports, never on a shared fallback; it expires after 30 minutes without use and is cleared whenever the checkpoint is paused or resumed. At most 20 reviews can wait for you per session; beyond that the assistant gets its own prompt.
• Journal and restore. Append-only, hash-chained journal per workspace; a restore point before every accepted write; rotation caps; a checkpoint→restore round-trip self-test in the Doctor.
• Fallback, never a hang. If ExplainIT stops responding, each hook gives up after the watchdog time (default 120 s). Claude Code then shows its own permission prompt. Codex has no such "ask" answer, so by default (explainit.checkpoint.codexUnresponsive = deny) the change is refused with a try-again reason and nothing lands unchecked; with passthrough Codex follows its own approval policy, and under full-auto that means the change lands without a prompt.
• No telemetry, no server, no keys, no accounts.
• The full threat model, the findings of the security review and the risks that remain are in docs/dev/SECURITY-REVIEW.md.

Limitations

• Copilot is review-after-landing, not a pre-write block: Copilot exposes no gating API. If that changes, ExplainIT will use it.
• The checkpoint gates the assistants' file-edit tools. Shell commands that write files are refused by default (explainit.checkpoint.shellWrites), which steers the assistant back to its edit tool; choose ignore and such writes are not inspected.
• Hooks apply to new assistant sessions; restart a session after connecting.
• When ExplainIT is not responding (window closed, frozen or reloading), the hook waits for the watchdog time (default 120 s) and then gives up. Claude Code falls back to its own permission prompt. Codex has no "ask" answer, so by default (explainit.checkpoint.codexUnresponsive = deny) the change is refused with a try-again reason and nothing lands unchecked; if you choose passthrough, Codex follows its own approval policy and under full-auto the change lands without a prompt. See runbook 4.
• Decision memory trusts the session id the assistant reports. ExplainIT cannot verify it, so "accept the rest of this session" could be inherited by a process that learns that id. The acceptance expires after 30 minutes without use and is cleared on pause/resume; turn explainit.checkpoint.allowAcceptRestOfSession off if you never want it.
• The change journal is hash-chained, not signed. It shows if entries were edited or removed in place; it cannot prove that a determined attacker with your user account did not rewrite the whole file. Keep a copy elsewhere if you need that.
• Codex requires a one-time trust of the hook (open codex in a terminal, choose Trust, or type /hooks); until then Codex changes are not stopped. The Doctor shows this, and cannot do it for you.
• Assistants change their hook formats over time. ExplainIT pins tested versions in its conformance suite and ships fixes through the Marketplace pre-release channel.
• Explanations come from your assistant's model and can be wrong; the twin says when a section is out of date, but it is a companion to the code, not a replacement for reading it.
• Twins are real files. They are excluded from git locally; other sync tools (Dropbox, cloud drives) will see them.
• Requires VS Code 1.100 or newer and real files on disk (no virtual workspaces).

Development

npm install
npm run typecheck
npm run test:unit
npm run test:integration   # launches VS Code with test/fixtures/workspace
npm run eval -- --channel claude   # explanation-quality round trip (needs a signed-in assistant)
npm run package

See architecture.md and docs/dev/CONTRACTS.md for the module seams.

License

MIT © Baharul Islam. See LICENSE.