Mudrik · مدرك

Name: Mudrik
Author: abdallahmagdy15

Stop pasting screenshots into AI chats. Mudrik is an open-source Windows AI assistant that sees what you see — and answers, acts, or guides you step-by-step through any task.

Website · Install · Hotkeys · About

🎬 Demo

Watch the demo →

Alt+Space → ask → Mudrik acts on your desktop

✨ What it does

Press Alt+Space anywhere on Windows. Mudrik scans your active window's UI — every button, field, label, and value — and opens a floating panel on the opposite side of your screen so nothing gets covered. The element you're pointing at becomes the focal anchor. For web apps and Chromium windows, Mudrik auto-attaches a screenshot, because browser UIA trees can miss page content.

From there: ask, translate, fix, summarize. Or tell it to act: type, paste, click, invoke, press shortcuts. Turn on Auto-Guide and Mudrik becomes a teacher — an owl cursor appears on screen and walks you step‑by‑step through any multi‑step task.

🚀 Install

Install Node.js ≥ 20.
Install OpenCode (auth optional — keys can live in-app):
```
npm i -g opencode-ai
```
Download the latest .exe from Releases and run it.
Configure your AI model. Launch Mudrik → click ⚙ → API Keys → paste a provider API key (Anthropic, OpenAI, Kimi, DeepSeek, …), then pick a model from the dropdown. Prefer the terminal? Run opencode auth login to use OpenCode-hosted models — no API key needed.

Installer is unsigned — SmartScreen will warn on first launch. More info → Run anyway.

From source: git clone https://github.com/abdallahmagdy15/mudrik && cd mudrik && npm install && npm start

Windows build prerequisite: npm install requires Visual Studio with the "Desktop development with C++" workload (for robotjs and koffi native compilation). Node.js ≥ 20 LTS recommended. See AGENTS.md for full details.

⌨️ Hotkeys

Two global hotkeys put Mudrik in front of you. Both are rebindable from the ⚙ menu.

Shortcut	What happens
`Alt+Space`	Scans the window's UI tree at your cursor. Mudrik opens on the opposite side of your screen, ready to help.
`Alt+X`	Quick chat — opens the panel instantly without capturing context. For questions that don't need screen awareness.
`Esc`	Cancel: stops streaming or closes the panel.
`Enter`	Send prompt. `Shift+Enter` for newline.

🛠 Features


🪟 Reads any Windows app	Uses Windows UI Automation to pick up buttons, fields, text, menus. Works in browsers, Office, IDEs, native dialogs — anywhere accessibility reaches. Auto-screenshot on Chromium apps; Capture Context button works for any app.
⚡ Acts for you	Type, paste, click, invoke, press keyboard shortcuts — Mudrik can interact with any accessible element.
🦉 Auto-Guide	Mudrik becomes a teacher: an owl cursor appears on screen, points to each target with a speech bubble, and walks you step‑by‑step through multi‑step UI tasks. Toggle in ⚙ settings.
💬 Quick chat mode	`Alt+X` opens the panel without capturing context — for questions that don't need screen awareness. Mudrik is always one keystroke away, even when you just need a quick answer.
🔌 Any LLM	18 providers out of the box — Anthropic, OpenAI, Google, DeepSeek, OpenRouter, Ollama, and more. Paste your key in settings — no terminal auth dance.
🔒 Sandboxed	No shell commands, no filesystem writes. The AI reads files in your working directory and dispatches an allow-listed set of UI actions. That's the whole capability surface.

🧠 How it works

Alt+Space (pointer)
  ↓  hotkey reads cursor position
  ↓  PowerShell UIA script — JSON tree of the active window
  ↓  Chromium/Electron? → auto-captures full-screen screenshot as fallback
  ↓  Mudrik opens on the opposite side of your screen, ready to chat

Alt+X (quick chat)
  ↓  panel opens instantly — no context capture
  ↓  for questions that don't need screen awareness

Send prompt
  ↓  streamed to `opencode run --agent readonly`
  ↓  tokens render live; <!--ACTION:{...}--> markers parsed
  ↓  actions execute via UIA or robotjs

Auto-Guide mode (opt-in via ⚙)
  ↓  AI emits guide_offer → user accepts
  ↓  owl cursor appears with speech bubble, panel hides
  ↓  owl points → user clicks → AI advances
  ↓  guide_complete → "Done!" → panel returns

Full architecture in AGENTS.md.

🔒 Privacy & Security

Mudrik runs the AI in a sandbox with deliberately narrow capabilities:

Capability	Exposed to the model?
Shell / PowerShell exec	❌ No
Filesystem write	❌ No
Filesystem read (`read`/`grep`/`glob`/`list`)	✅ Yes (within working directory)
Windows UI Automation	✅ Yes (pre-defined action set)
Keyboard / mouse	✅ Yes (when UIA can't reach a target)
Screen pixels	✅ Auto on Chromium/Electron · 🖐️ Manual on native apps

Full threat model + reporting in SECURITY.md.

👋 About

Hi, I'm Abdullah Magdy.

A senior dev who got tired of pasting screenshots into ChatGPT — so I built Mudrik on nights and weekends. Open source so you can see (and improve) every line.

🐙 GitHub — @abdallahmagdy15
🐦 X / Twitter — @AbdallahMagdyy
💼 LinkedIn — abdallahmagdy15
✉️ [email protected]

For security issues use GitHub Private Vulnerability Reporting (or email as fallback) — not public issues.

🤝 Contributing

PRs welcome. Mudrik is TypeScript end-to-end (main, preload, renderer, shared types) — the single source of truth for IPC channels, action types, and config shape lives in src/shared/types.ts.

Setup, build pipeline, and release flow in CONTRIBUTING.md. Code of Conduct in CODE_OF_CONDUCT.md.

🙏 Acknowledgements

OpenCode — handles streaming, providers, auth so Mudrik doesn't have to.
Electron · React · robotjs · Windows UI Automation.

📄 License

MIT — fork it, modify it, ship it, sell it. Just keep the copyright notice in the LICENSE file.

_{Mudrik · مدرك · the aware}