<div align="center">

# 🧭 Ekran Rehberi · Screen Guide

**Claude points. You click.**
A tiny Windows overlay that shows *where* to click, copy, paste or drag, with colored boxes,
short labels and a ghost cursor, step by step. Built to help people with ADHD stay focused.

**🇬🇧 English** · [🇹🇷 Türkçe](README.tr.md)

[![Stars](https://img.shields.io/github/stars/semihcarter5/ekran-rehberi?style=for-the-badge&logo=github&color=f5c518)](https://github.com/semihcarter5/ekran-rehberi/stargazers)
[![Tests](https://img.shields.io/github/actions/workflow/status/semihcarter5/ekran-rehberi/test.yml?style=for-the-badge&label=tests)](https://github.com/semihcarter5/ekran-rehberi/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=for-the-badge)](LICENSE)
![Windows](https://img.shields.io/badge/Windows-10%20%7C%2011-3b82f6?style=for-the-badge&logo=windows)
![Python](https://img.shields.io/badge/python-3.11+-a855f7?style=for-the-badge&logo=python&logoColor=white)

<img src="docs/demo-en.gif" alt="Screen Guide demo: colored boxes and a ghost cursor guide the user step by step" width="860">

### ⭐ If this helps you, please give it a star. It helps other people find it.

</div>

---

## 💡 Why?

You ask an AI for help and get back: *"Open the folder, copy the file, go to the page, click Upload,
drag it in…"* Then you're left staring at the screen wondering **where** all that is.

Screen Guide puts the instructions **on your screen**, one step at a time:

- 🟩 **1. Copy the logo**: a green box around the file and a `Ctrl+C` badge
- 🟦 **2. Click Upload**: a blue box, and a ghost cursor shows you the click
- 🟧 **3. Drag it here**: the ghost cursor carries the file from A to B
- ✅ When you finish a step it turns green and **the next one appears by itself**

You stay in control: the guide only *shows*, and you do the clicking.

## ✨ Features

| | |
|---|---|
| 🎯 **One step at a time** | Big number, ≤ 6-word label, nothing else to distract you |
| 🎨 **A color per action** | click 🟦 · copy 🟩 · paste 🟨 · drag 🟧 · type 🟪 · look ⬜ |
| 👻 **Ghost cursor** | Shows the movement, and you follow it with your own mouse |
| ⚡ **Auto-advance** | Detects the click, copy, paste, drag or typing and moves on |
| 🔍 **Finds things by name** | `"Chrome > Upload"` is located through Windows UI Automation, with no screenshots |
| 🪶 **Low token usage** | Claude sends all steps in **one** call, and tracking runs locally |
| 🤖 **Opens automatically** | The MCP server tells Claude to use it whenever you have manual steps |
| 🌍 **Turkish & English UI** | Follows your Windows language. Adding a new language takes one dictionary |

## ⚙️ How it works

```mermaid
flowchart LR
    A[You ask Claude] --> B[Claude answers<br/>+ calls rehber_goster]
    B --> C[MCP server]
    C -->|localhost JSON| D[Overlay app]
    D --> E[UI Automation<br/>finds 'Upload']
    E --> F[🟦 box + ghost cursor]
    F --> G{You did it?}
    G -->|click / copy / paste / drag| H[✅ next step]
    G -->|I'm stuck| I[Claude takes ONE screenshot<br/>and fixes the box]
```

## 🚀 Install (Windows 10/11)

```bash
git clone https://github.com/semihcarter5/ekran-rehberi.git
```
```bash
cd ekran-rehberi
```
```bash
python -m venv .venv
```
```bash
.venv\Scripts\pip install -r requirements.txt
```

### Connect to Claude Code

```bash
claude mcp add ekran-rehberi -s user -- "C:\FULL\PATH\ekran-rehberi\.venv\Scripts\python.exe" "C:\FULL\PATH\ekran-rehberi\mcp_sunucu.py"
```

### Connect to Claude Desktop

Add this to `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ekran-rehberi": {
      "command": "C:\\FULL\\PATH\\ekran-rehberi\\.venv\\Scripts\\python.exe",
      "args": ["C:\\FULL\\PATH\\ekran-rehberi\\mcp_sunucu.py"]
    }
  }
}
```

That's it. The overlay starts in the background the first time it's needed.

## 🧪 Try it without Claude

```bash
.venv\Scripts\python goster.py ornekler\demo.json
```

| Command | What it does |
|---|---|
| `goster.py file.json` | Show the steps |
| `goster.py --durum` | Current step / status |
| `goster.py --sonraki` | Skip to the next step |
| `goster.py --temizle` | Clear the screen |
| `goster.py --cikis` | Quit the overlay |

**Shortcuts:** `Ctrl+Shift+Space` next step · `Ctrl+Shift+End` close · drag the panel to move it.
**Language:** set `EKRAN_REHBERI_DIL=en` or `tr` to override the Windows language.

## 📝 Step format

```json
{
  "baslik": "Upload the logo",
  "adimlar": [
    {"tur": "kopyala", "yazi": "Copy the logo", "hedef": "Explorer > logo.png"},
    {"tur": "tikla",   "yazi": "Click Upload",  "hedef": "Chrome > Upload|Yükle"},
    {"tur": "surukle", "yazi": "Drag it here",  "hedef": "Explorer > logo.png", "birak": "Chrome > Drag files here"},
    {"tur": "yaz",     "yazi": "Type the name", "hedef": "Chrome > Repository name", "metin": "my-project"}
  ]
}
```

- `tur` (type): `tikla` click · `kopyala` copy · `yapistir` paste · `surukle` drag · `yaz` type · `bak` look.
  English aliases (`click`, `copy`, `paste`, `drag`, `type`, `look`) work too.
- `hedef` (target): `"Window > visible text"`. Use `|` for alternatives: `"Taskbar > Başlat|Start"`.
- `kutu` (box): `[x, y, width, height]` in real screen pixels, when you know the exact spot.

## 🤝 Contributing: help wanted!

This project is small, friendly and **looking for contributors**: first-timers are very welcome.

- 🐛 Found a bug? [Open an issue](https://github.com/semihcarter5/ekran-rehberi/issues/new/choose)
- 💡 Have an idea? Start a [discussion](https://github.com/semihcarter5/ekran-rehberi/discussions)
- 🛠️ Want to code? Pick a [`good first issue`](https://github.com/semihcarter5/ekran-rehberi/labels/good%20first%20issue)

Ideas we'd love help with: **macOS / Linux support**, more languages, sound cues, a settings window,
a one-file `.exe` release, and accessibility testing.

👉 Read the **[contributing guide](CONTRIBUTING.md)**. It explains the code (including the Turkish names) in 5 minutes.

## 🔒 Privacy

Everything runs locally. Mouse and keyboard listeners only check whether the current step is done.
Nothing is recorded or sent anywhere.

## 📄 License

[MIT](LICENSE): free to use, change and share.

<div align="center">

---

### ⭐ Don't forget to star the repo!
Every star helps more people (and more people with ADHD) find this tool.

[![Star this repo](https://img.shields.io/github/stars/semihcarter5/ekran-rehberi?style=social)](https://github.com/semihcarter5/ekran-rehberi/stargazers)

</div>