Skip to main content
Glama
README.md
<img alt="TutorialOverlay — lessons drawn on top of any Windows app" src="docs/media/logo.webp" width="100%">

<b>English</b> · <a href="README.ru.md">Русский</a>

Step-by-step tutorials drawn right on top of any Windows app — led by an AI agent.

<img alt="A lesson in FL Studio: the mascot points at the step cells, the card ticks off each step" src="docs/media/fl-lesson.webp" width="800" />

The lesson above was played through by the project's test robot in FL Studio.

## Tutorial

To get started, [install TutorialOverlay](#installation) and ask your AI agent how to do something in an app:

> [!TIP]
> *“Walk me through turning on word wrap in Notepad, step by step”*

The agent reads the app's interface over MCP and writes the lesson — steps, targets and a *why* for each one:

```json
{
  "title": "Word wrap in Notepad",
  "app": "Notepad",
  "steps": [
    {
      "title": "Open the View menu",
      "why": "Notepad keeps everything about how text looks in the View menu.",
      "targets": [{ "name": "View", "anchor": { "element": { "name": "View", "role": "MenuItem" } } }]
    },
    {
      "title": "Close the menu with Esc",
      "until": [{ "type": "key", "keys": "Esc" }]
    }
  ]
}
```

The overlay rings each target on top of the app, the mascot points at it, and a step card leads the way. Steps
complete by themselves — a click, a pixel, a window, a shortcut, a drag, a scroll. Stuck? Press **Help** and the
agent answers right in the card. At the end the lesson can be saved and replayed from the tray, no agent needed.

<img width="420" alt="The step card: Why opens, Help offers choices, the agent's answer appears, the end card offers Save tutorial" src="docs/media/card-help.webp" />

For the full spec format see [`docs/tutorials.md`](docs/tutorials.md).

## Installation

> [!NOTE]
> Windows 10 or 11, x64. Nothing else: .NET is inside the exe.

TutorialOverlay is a local MCP server, so any agent that speaks MCP can drive it. Download
`TutorialOverlay-<version>-win-x64.zip` from [Releases][releases], unzip it (say to `C:\Tools\TutorialOverlay`) and
put it on `PATH` as `tutorial-overlay`:

```powershell
Copy-Item C:\Tools\TutorialOverlay\TutorialOverlay.exe C:\Tools\TutorialOverlay\tutorial-overlay.exe
$p = [Environment]::GetEnvironmentVariable('Path', 'User')
[Environment]::SetEnvironmentVariable('Path', "$p;C:\Tools\TutorialOverlay", 'User')
```

Then, in **Claude Code**, install the plugin — the server plus the skill that teaches the agent to write good
lessons:

```text
/plugin marketplace add kizrum/tutorial_overlay
/plugin install tutorial-overlay@tutorial-overlay
```

That's all: no key, no port. The agent starts the overlay when it needs it, and it stays in the tray until you
quit it from the tray menu.

> [!TIP]
> Claude Code with the plugin works best. Other agents get the same tools and the server's short instructions, but
> not the skill.

<details>
<summary>Codex</summary>

Add to `~/.codex/config.toml` (or `.codex/config.toml` in a project):

```toml
[mcp_servers.tutorial-overlay]
command = "tutorial-overlay"
args = ["--stdio"]
```

</details>

<details>
<summary>Claude Code without the plugin, other MCP clients</summary>

Add a local (stdio) MCP server: the command `tutorial-overlay` (or the full path to `TutorialOverlay.exe`) with the
argument `--stdio`. In Claude Code:

```powershell
claude mcp add --scope user tutorial-overlay -- tutorial-overlay --stdio
```

Do not add it this way next to the plugin: the agent would see every tool twice. Clients that speak Streamable HTTP
can also connect to the running overlay directly — see [`docs/server.md`](docs/server.md).

</details>

<details>
<summary>Updating</summary>

Quit TutorialOverlay from the tray menu, unzip the new version over the old folder and copy `TutorialOverlay.exe` to
`tutorial-overlay.exe` again. Settings, the key and saved tutorials live in `%LOCALAPPDATA%\TutorialOverlay` and
stay as they are; the agent's settings stay right too.

</details>

## Building from source

Needs the [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0). From the repository root:

```powershell
# build: publish\TutorialOverlay.exe
dotnet publish -c Release -o publish

# run the tests
dotnet run --project tests

# use your build in Claude Code
claude mcp add --scope user tutorial-overlay -- "$PWD\publish\TutorialOverlay.exe" --stdio
```

`.\release.ps1` builds the release zip. How the program is built inside is in
[`docs/development.md`](docs/development.md).

## Reference

- [Server](docs/server.md) — command-line options, the tray icon, settings, `config.json`, security, the log
- [MCP tools and events](docs/tools.md) — what the agent can call and what it gets back
- [Tutorials](docs/tutorials.md) — the spec format: shapes, anchors, steps and conditions, the mascot, help
- [Development](docs/development.md) — the inside of the program, the tests, the test robot

## License

[MIT](LICENSE)

***

<img src="docs/media/mascot-outro.webp" width="140" alt="Shazhok, the mascot, dancing" />

Shazhok says hi. Like everything else here, it is drawn in code — no images, no fonts, no packages.

[releases]: https://github.com/kizrum/tutorial_overlay/releases/latest