Skip to content

getting-started.md

Latest commit

 

History

History
130 lines (89 loc) · 3.64 KB

getting-started.md

File metadata and controls

130 lines (89 loc) · 3.64 KB
Raw

Getting started

This guide takes you from installation to a first ExplainGate session.

Documentation · Visual artifacts · Workflows · Gates and data · Troubleshooting

What you need

  • Claude Code or Codex
  • Git, for batch and review workflows
  • Bash for command gates: macOS, Linux, WSL, or Git Bash on Windows
  • The GitHub CLI (gh) when reviewing pull requests

You can still use system, study, and drill modes without GitHub.

Install for Claude Code

Run:

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

You can also run the equivalent commands inside a Claude Code session:

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

Restart the session, then invoke /explaingate or ask for a quiz in plain language.

Install for Codex

Run:

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 discovers the installed skill.
  3. Invoke $explaingate or ask for a quiz in plain language.

Complete your first session

Open a repository containing work on a branch and ask:

Client Prompt
Claude Code /explaingate
Codex $explaingate
Either Quiz me on this branch before I push.

ExplainGate will:

  1. Identify the branch changes.
  2. Ask one question and wait for your answer.
  3. Teach anything important you missed.
  4. Ask a different question about the same concept.
  5. Write the pass marker only after you demonstrate understanding.
  6. Save a card for later recall.
  7. Create a polished visual artifact and return a link to it.

The default batch session uses about four questions. Short, precise answers are welcome; this is not a writing test. The artifact is a self-contained HTML page saved under ~/.explaingate/artifacts/; read Visual artifacts for its contents and privacy model.

Try another workflow

Review PR 64 and check whether I understand it.

Help me learn this codebase well enough to walk through its architecture.

Help me absorb docs/design.md and make cards from it.

Run a five-minute drill on whatever is due.

See Workflows for the exact behavior and command form of each mode.

Optional: gate terminal pushes too

The plugin hook covers commands issued through the coding agent. A native Git hook also covers pushes from an ordinary terminal.

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 your user account:

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

The installers refuse to overwrite an existing hook configuration. Read Gates and local data before enabling the global option.

Upgrading from Teachback

The project and plugin ID changed to ExplainGate in version 0.4. Install the new explaingate@explaingate package so clients discover $explaingate or /explaingate.

Old cards are not read from ~/.teachback. To preserve them:

mkdir -p ~/.explaingate
cp ~/.teachback/deck.md ~/.explaingate/deck.md

Old pass markers intentionally do not migrate; complete a fresh quiz for the current commit or pull request.

If anything does not appear or remains blocked, continue with Troubleshooting.