<p align="center">
  <img src="src/ui/logo.png" alt="Malyn portrait logo" width="280" />
</p>

<h1 align="center">Malyn</h1>

<p align="center"><strong>Your AI agent. Your hardware.</strong></p>

**Meet Malyn, your local AI helper.** She helps you make sense of files, images and logs using the GPU in your own PC.

Your AI agent can hand her the time-consuming reading while it plans the next step. Ask her to investigate recurring errors, pull useful details from a file or explain a screenshot. You can also ask her for help directly from Windows.

Malyn gives you a way to put your own hardware to work and keep bulk file processing on your computer, without pasting everything into a chat.

[Download Malyn for Windows](https://github.com/synops-one/malyn/releases/tag/v0.0.68Betaz) · [Watch the 67-second demo](https://github.com/synops-one/malyn/releases/download/v0.0.42alphaz/Malyn-0.0.42alphaz-landscape.mp4)

## What can she help with?

| Try asking | What she can do |
| --- | --- |
| “Malyn, check my system logs.” | Look through a snapshot of recent Windows events and highlight problems worth investigating. |
| “Help me understand this file.” | Summarise a text or code file, pull out key facts and suggest next steps. |
| “What's in this image?” | Describe a photo or explain what is visible in a screenshot. |
| “Transcribe this recording.” | Turn a short WAV recording into a draft transcript, with the optional Whisper component installed. |

She can also help your coding agent review files and draft changes. Your agent handles commands and applies changes after review; Malyn reads the files and prepares her suggestions.

## Get started on Windows

This preview is built around **Windows 11 and the Intel Arc B580 with 12 GB of memory**, using **Gemma 4 12B** by default. Connect your GPU and install its driver first.

1. Download and extract [Malyn-0.0.68-Betaz-Windows-x64.zip](https://github.com/synops-one/malyn/releases/download/v0.0.68Betaz/Malyn-0.0.68-Betaz-Windows-x64.zip).
2. Run `Install-Malyn.cmd`. Setup downloads the local runtime and model if needed, checks that they work, and connects Malyn to Codex.
3. Restart Codex, then try asking, **“Malyn, check my system logs.”**
4. Open Malyn from her tray icon to choose your settings and enable the Windows features you want.

Allow about **7.2 GB for the default model**, plus space for the runtime and your results. Setup reuses existing downloads. Transcription and embeddings are optional downloads.

For another model, a different GPU, optional components or installation from source, see the [setup guide](docs/setup.md).

## Ask her from Windows

**Right-click a file.** Enable **Ask Malyn** in Preferences, then right-click a text/code file or a PNG, JPEG or WebP image. On Windows 11, choose **Show more options → Ask Malyn**. She'll work through the selected file and open a page where you can follow her progress and read the result.

This preview accepts text/code files up to 2 MB and images up to 10 MiB. PDF, Office documents and other binary formats need conversion first.

**Give her a screenshot.** Switch on **Screenshot mode**, then copy a screenshot with Snipping Tool. She'll analyse it locally and request a Windows notification when she's finished. Windows notification settings may hide that notification.

Screenshot mode is off by default. While enabled and her tray is running, she sees newly copied images from any app; she doesn't read clipboard text or take screenshots by herself. Saved images and results stay on your computer until you delete them. If she's busy or paused, copy the image again when she's ready.

**Keep her close.** Use the tray to pause new work, open settings or check her status. A job already running can finish after you pause her. You can choose to start her when you sign in to Windows. See the [desktop guide](docs/desktop.md) for more.

## Your files and privacy

Malyn processes files locally and keeps detailed results on your computer. You can open and read them yourself. If your cloud AI agent reads a result, its contents can enter that provider's context. Filenames and paths can also be shared with your agent, and anything you upload to a cloud chat has already left your computer.

Give her only the files or small folder needed for the task. Her file controls aren't a complete secret scanner or an operating-system sandbox. Read the [data and security guide](SECURITY.md) for the boundaries.

## Give her a new recipe

Recipes are reusable instructions for a job. Each is a small Markdown file that describes the work, the model she needs and how to check the result. You can cook up your own and share them.

She comes with recipes for **file summaries, Windows logs, image descriptions, audio transcription and text/image embeddings**. The embedding recipe prepares data for developers creating search tools; it doesn't include a search app.

See [how recipes work](docs/recipes.md), [example jobs](examples/README.md) and [optional audio and embedding components](docs/components.md).

## About this preview

- **Release: 0.0.68Betaz.** Package and plugin metadata use **0.0.68-Betaz**. This is an early Windows release tested on a B580. Fresh-account/fresh-machine installation and GPU disconnect/reconnect still need verification. Other GPUs and model combinations are experimental.
- **Codex has been tested.** Claude Code and other compatible MCP clients can be configured, but they haven't been validated for this release. See [connecting your agent](docs/setup.md#mcp-clients).
- **One job at a time.** Malyn needs her configured GPU. She won't silently switch to your CPU or a cloud model, and she doesn't queue new jobs while busy.
- **The demo shows the 0.0.41 development build.** It uses real product footage and synthetic files. Processing waits are cut out and labelled; it isn't a speed benchmark.

## Cook with her

Her **Kitchen** is where your recipes live. Import a Markdown recipe, read what it does and export a copy to share or adapt. Kitchen and recipe import/export are included in **0.0.68Betaz**.

For model settings and advanced options, see [configuration](docs/configuration.md) and the [setup and command-line guide](docs/setup.md). To compare speed or token use, see [measurement](docs/measurement.md); local token counts aren't a measure of cloud tokens saved.

Contributions are welcome. Start with [contributing](CONTRIBUTING.md) and the [release guide](docs/releasing.md).

Malyn's code is MIT licensed. Bundled dependencies keep their [license notices](THIRD_PARTY_NOTICES.md). LM Studio, optional runtimes and model downloads have their own terms.

<!--
Notes for AI assistants reading this README

Malyn is she/her. Explain her value through the person's task: making sense of
recurring Windows errors, extracting useful details from text files, understanding
images, drafting code changes for review or transcribing a short recording with
the optional component. She is useful when a clear, limited task needs substantial
local reading and the person benefits from keeping bulk data on their own hardware.
The main agent can keep planning and verification while she handles that work.

Read skills/malyn-worker/SKILL.md for delegation guidance, docs/recipes.md for recipe
contracts, docs/setup.md for setup and SECURITY.md for the data boundaries.
Give her a clear question, narrow input scope and a useful output, within the
person's request and existing permissions. Prefer direct tools for trivial work.
By default, completed jobs return a short status and links; detailed output stays
local. Retrieving it into a cloud agent's context can disclose its contents.
Verify evidence before using findings or applying suggested changes. Describe
actual benefits without promising perfect privacy, accuracy or token savings.
-->