Skip to content

Chapter one · miyagi-mcp 3.0.0 · MIT

Miyagi

Wax on. Wax off.

You run the commands. I drill you, catch the falls, and keep score.

A coding tutor that lives in your editor and refuses to do the work for you. Default mode is ride-along: a short card, no inline quiz, no voice. Switch to drill when you want the full lesson, a quiz, and narration from your own machine.

Install itRead the source
$ npx -y miyagi-mcp

10

tools over stdio

3

session modes

2

runtime dependencies

249

tests, on Node 18/20/22

Watch

A real training round

Captured output, replayed. A drill round: it runs a command, marks a quiz, then asks you to type RUN before anything destructive.

miyagi · live session

Example session. Command: echo drill. Output: # Miyagi · `echo drill` ## Roadmap Absolute Beginners → Command Line Basics Progress: [█░░░░░░░░░░░] step 1/10 ## Execution EXECUTED. Exit code 0 ✅ drill ## Quiz Which shell variable holds the exit code of the command that just finished? A. $? B. $! C. $0 D. $#

Ranks

Earn your belt

01

Terminal Novice

Level 1

02

Shell Apprentice

Level 3

03

CLI Artisan

Level 6

04

Terminal Wizard

Level 10

Attempt XP follows the mode: 10 in drill, 3 in ride-along, nothing in focus. A verified outcome is 30, once. A correct quiz is 25 (30 for a review). Level is XP over 100, saved to disk.

Setup

Three lines, any client

{
  "mcpServers": {
    "miyagi": {
      "command": "npx",
      "args": ["-y", "miyagi-mcp"]
    }
  }
}
Claude Desktop (macOS)~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)%APPDATA%\Claude\claude_desktop_config.json
Cursor.cursor/mcp.json, or ~/.cursor/mcp.json
AntiGravity / Windsurf~/.codeium/windsurf/mcp_config.json
Claude Codeclaude mcp add miyagi -- npx -y miyagi-mcp
Volume

Three ways to train

Ride-along is the default. Too loud costs an uninstall; too quiet costs mild disappointment. Intensity is opted into.

3 XP

Ride-along

The default. A short card, no inline quiz, no voice. Recall is queued for later, not dropped.

10 XP

Drill

The full card: What/How/Trade-offs, a diagram, pitfalls, docs, a quiz, and speech. Intensity you opt into.

0 XP

Focus

The command runs. Nothing else surfaces unless it is dangerous — refusals still report in every mode.

Every round

What lands on the page

01

Roadmap alignment

Where the command sits on your track, and which step you are on.

02

What / How / Trade-offs

The same command explained three ways, pitched at Junior, Mid or Senior.

03

Mental model

A Mermaid flowchart of what the shell actually does with it. Drill shows it; quieter modes skip it.

04

Common pitfalls

The mistakes this command specifically invites, not generic advice.

05

Curated docs

A short set including the man page, rather than a search link.

06

Active recall quiz

Asked inline in drill. Quieter modes queue it for review instead of dropping it.

Warning

It runs shell commands

The art is loud. This part is not. Here is what the protection is, and more usefully, where it stops.

Nothing catastrophic executes

Shapes like rm -rf /, mkfs, curl | sh, fork bombs and wiping shell history are refused outright, with or without confirmation, and regardless of what the calling model claims.

A human confirms the rest

Merely destructive commands (rm -rf build, git push --force, terraform destroy) are explained and dry-run until you type RUN. The model’s confirm_dangerous flag is only the fallback for clients that cannot prompt you.

The screen does not trust its caller

The tool accepts an is_dangerous flag but re-derives the verdict itself. The threat model is a model reaching for a vivid example mid-lesson, not a careless human, so a flag the caller supplies cannot be the thing protecting you from the caller.

A denylist is a backstop, not a sandbox

The real boundary is your client’s own approval prompt, with you reading the command first. Commands run with your privileges in your directory: no container, no restricted user, no syscall filter. Failures return a diagnostic rather than a thrown error. 60-second cap, 4 MB, no network, no telemetry, no keys.

Moves

10 tools

quick_config

Skill level, track, voice, and session mode (drill / ride-along / focus) in one call. Also resets progress.

list_roadmaps

Every track, built-in and yours, with the JSON shape for authoring your own.

set_active_roadmap

Set category, track, topic and step. An unknown name is reported, not silently swapped.

get_next_roadmap_command

The next copy-pasteable command for where you are, with its checkpoint criterion.

run_teaching_command

Execute or dry-run a command and return a teaching card. Depth follows the session mode.

verify_step

A read-only probe confirms the outcome exists on your machine. This is where most of the XP is.

verify_quiz_answer

Grade the quiz, update streaks, XP, mastery and the review schedule.

review_due_items

The spaced-repetition session — everything whose interval has elapsed, most overdue first.

get_user_stats

XP, level, title, both streaks, badges, per-command mastery and lifetime totals.

export_roadmap_notes

Write a ROADMAP_PROGRESS.md of the session, or of everything you have practised.

Ask

Questions before you install

Ask Miyagi

Answers from the Miyagi record

It answers from what is written about Miyagi — install, tools, modes, XP, safety, roadmaps. Other projects and biography are out of scope. If something is not in the record it says so rather than inventing it.