Welcome to Mipsy

Mipsy is your scratchpad for talking to AI models that run on your own Mac. Mipsy was designed by Michael Mangelsdorf at Swirlsea.org in 2026.

“Mipsy is a tool that I like using and which I personally find helpful for a variety of tasks. I would love to hear from you if this app is useful to you over time! In the case that you would like to show your appreciation, I have a printshop where I sell decorative prints I make if you are interested.”

Mipsy is one half of Acopa; the other half is Roller, a stage for playing scenes with a model. Click Roller next to Mipsy at the top left to switch (and Mipsy there to come back; in the ZIM view the two are hidden, so leave it first). Roller has its own Help. Both share the models, the speech settings, the port and one password, and Roller shows your Vault stories below its World tree.

In the words of the author of SQLite, which incidentally is a central piece of this app:

The author disclaims copyright to this source code. In place of a legal notice, here is a blessing: May you do good and not evil. May you find forgiveness for yourself and forgive others. May you share freely, never taking more than you give.

Getting started

At the top of the middle column you pick who answers you:

Then choose a model from the list, type something into Query and press Query. That's it.

The text boxes

The middle column has three boxes:

The column on the right holds six parking boxes, handy spots to keep snippets you want to reuse.

Below the file tree on the left is the STDOUT box. It shows what a script prints (see Running scripts), but otherwise it's a box like any other: type in it, drag text in and out, keep things there.

All boxes work the same way:

Asking a question

Press Query (or ⌘↵). Your question and the answer are added to Context, so it grows into a running conversation the model can see. While an answer is coming in, the button says Stop. Press it (or Esc) to stop early; whatever already arrived is kept.

The first question after picking a model takes longer: the model has to be loaded into memory first. A window shows how far it has come (for Local models step by step, with how much is already in memory) and closes as soon as the model gives its first answer; Cancel stops the loading. After that the model stays loaded, and the next questions start right away. While you wait, the status line says what is happening: Loading the model, Reading the prompt (a long Context takes a while to read, even with the model loaded), Thinking (models that reason first, with a word count), then Generating the answer.

The bar at the bottom shows how much of the model's memory your Context uses. If it turns red, the text is too long for the model. Remove some, or pick a model with more room.

Clear empties all the boxes, STDOUT included, and the ZIM reader with its back/forward history, closes everything in the ZIM tree, and makes the six parking boxes equally tall again. The Payload switch shows exactly what will be sent to the model, which is useful when an answer surprises you.

Your files

The left side shows your files and folders. Every file remembers its last 10 versions, so you can't lose a good draft by accident.

A folder as one document

Dragging a folder into a box puts its files together into one text. So you can split a long text into parts, keep each part as its own file, and edit just the bit you care about, with its own version history.

Take a C program. Make a folder calc.c and put one file in it for each piece:

calc.c/
  01 header comment.c
  02 includes.c
  03 struct stack.c
  04 push and pop.c
  05 main.c

Now you can drag just 04 push and pop.c into Query, ask the model to improve it, and drop the better version back onto that file. Drag the whole calc.c folder into a box to get the complete program again.

How the parts are put together:

Running scripts

Any file ending in .sh is a little program you can run. Right-click it and choose Run .sh. Right-click one of its older versions to run that version instead.

A tiny example, a script that runs whatever Python code you typed into Query (the result appears in STDOUT):

python3 "$MIPSY_QUERY"

One that counts the words in Context:

wc -w < "$MIPSY_CONTEXT"

And one that turns the first parking box into capital letters:

tr a-z A-Z < "$MIPSY_PARKING_1" > up.tmp
mv up.tmp "$MIPSY_PARKING_1"

Let an AI write a script for you

You don't have to write scripts yourself. Copy the text below into Query, add what the script should do at the end, and ask your model (or any other AI). The text explains to the AI how Mipsy works, in the AI's own technical language, so you can simply talk about “Parking Box 2” or “the Context box”.

Write a shell script for Mipsy, a local LLM scratchpad web app (Node.js server, macOS). Runtime facts:

UI LAYOUT (three columns, left to right)
- Left: the file tree (a view of the directory $MIPSY_FILETREE on disk), and below it a text pane "STDOUT" that receives the script's output.
- Center: three text panes stacked vertically, top to bottom:
  1. "System": the system prompt.
  2. "Context": the chat transcript. Turns start with a line "### User" or "### Assistant"; the text before the next such line is that turn's content.
  3. "Query": the next user message.
- Right: six "Parking Boxes" stacked vertically, numbered 1 (top) to 6 (bottom). Free-form text storage.

EXECUTION
- The user right-clicks the script in the tree and chooses "Run .sh". Interpreter: /bin/sh, unless line 1 is a shebang (e.g. #!/bin/bash or #!/bin/zsh; it is split on whitespace, extra arguments allowed).
- Working directory: the directory containing the script, inside $MIPSY_FILETREE.
- stdin: empty (closed immediately). All input comes from the files below.
- stdout and stderr: streamed interleaved into the STDOUT pane as they arrive, replacing its previous content. Cap 5 MB, then the script is killed. A non-zero exit appends "[exit N]". The user may kill the script at any time (SIGTERM to the process group, SIGKILL after 2 s).
- Environment variables holding absolute paths of temporary UTF-8 text files (hidden dotfiles in the working directory):
  $MIPSY_QUERY      = Query pane
  $MIPSY_CONTEXT    = Context pane
  $MIPSY_PROMPT     = System pane
  $MIPSY_PARKING_1 … $MIPSY_PARKING_6 = Parking Boxes 1 … 6
  Read them like normal files. To change a pane, overwrite its file (e.g. write a temp file, then mv it onto "$MIPSY_PARKING_2"). After the script exits (any exit code; not when killed), each file whose content changed is loaded into its pane; unchanged or deleted files leave the pane as it was. The files are deleted afterwards. STDOUT has no file; it only receives the output.
- $MIPSY_FILETREE: absolute path of the file tree's root directory.

FILE TREE CONVENTIONS (directory $MIPSY_FILETREE)
- Folders are plain directories. Names starting with "." are hidden from the tree.
- Each file in the tree is a version stack of up to 10 versions, stored as separate files with the version number before the last extension: notes--0.md (newest) … notes--9.md (oldest). Without an extension: notes--0 … notes--9. The lowest number present is the newest version. Logical file names may not end in "--<digit>".
- A plain file without a suffix (notes.md) is a single-version file and counts as version 0.
- To read the newest version of "notes.md": use notes.md if it exists, else the lowest-numbered notes--N.md.
- To add a new newest version: write the plain file notes.md next to the existing notes--N.md files. When the tree refreshes (automatically after the script ends), Mipsy renames it to notes--0.md, shifts the older versions down by one and drops anything beyond 10 versions. Do not renumber the files yourself.
- To create a new file: write the plain name (e.g. summary.txt).

REQUIREMENTS
- Return one complete script, POSIX sh unless a shebang says otherwise, quoting all paths ("$MIPSY_CONTEXT" etc.; paths may contain spaces).
- Print only what should appear in the STDOUT pane; put results meant for other panes into their files.

TASK

Scripts can do anything you could do in Terminal, including deleting files. Only run scripts you understand.

Stories

The book icon in the bottom-right corner of the tree view switches to your stories: a place for longer writing, organised as folders → stories → chapters → scenes → moments.

Synopses: keep big chapters small

A model can only take in so much text at once. Once a story grows, dragging whole chapters into Context quickly fills the bar at the bottom. Synopses help here: give a scene a short summary, or write an LLM prompt to generate one for you, and you choose with a checkbox per scene whether the model sees the full text or just the summary.

A good mix: summaries for the early chapters the model only needs to remember, full text for the scene you're working on and the ones right before it.

ZIM files (offline Wikipedia & co.)

A .zim file is a whole website packed into one file for reading offline: Wikipedia (all of it, or a topic), Wiktionary, Stack Exchange sites, Project Gutenberg and many more. Get them from library.kiwix.org. Many come in three sizes: maxi (full articles with pictures), nopic (full articles, no pictures) and mini (only the opening part of each article).

Searching well

Where it searches: in the ZIM file, folder or group that is selected in the tree, and only in the ZIM files that are ticked. Each ZIM file has a checkbox: untick the ones you don't want in your searches (Stack Exchange sites, say, when you're after encyclopedia articles); they are shown faded. A ZIM file you select itself is always searched. Clicking an article selects its ZIM file, so the next search stays in that file; the search field says where it searches (“Search Wikipedia …”, “Search 3 ticked ZIM files …”). To search all ticked files again, click the top ZIM row of the tree. The ⌃⌄ button at the top closes everything in the tree again (Collapse all).

The two kinds of search work differently:

Nothing found? Use fewer words: each extra word must also be in the article. Two or three telling words usually work best. And check where it searched (see above).

Your own books (EPUB)

E-books in the .epub format can be turned into ZIM files, so you can read them in the reader, search their full text, drag passages into your boxes and ask the model about them, just like Wikipedia articles.

The ZIM view needs libzim, which acopa.command installs once by itself. If the tree says libzim is missing: in Terminal, in the Acopa folder, run export PATH=/opt/homebrew/bin:$PATH and then npm install (it needs Node 22 or newer, and Apple's command-line tools: xcode-select --install).

When you drag something very long (over 1,000 lines) into Context, Mipsy puts in a short placeholder like ⟦#3 📄 novel · 4,402 lines⟧ instead, so everything stays fast. The full, current text is still used when you ask a question. Double-click the placeholder if you want the whole text in the box.

Thinking (Fold)

Some models “think out loud” before they answer. With Fold pressed in, that thinking is tucked away into a one-line placeholder so Context stays readable. Press Fold again to see all of it, or double-click a single placeholder to open just that one. The thinking is never sent back to the model.

Listen & Speak

Both run entirely on your Mac and need a one-time setup.

Getting models

A model is one big file that holds an AI's “knowledge”. Mipsy's Local backend runs models in the GGUF format (files ending in .gguf). It finds them in two places:

After adding a model, press the little refresh arrow next to the model list (with Local selected).

Where models come from: Hugging Face

Hugging Face is the big public library of AI models, a bit like an app store where anyone can publish. The companies that make models (Mistral, Google, Meta, Alibaba's Qwen and others) put them there, and volunteers convert them into GGUF files for programs like Mipsy and LM Studio. Downloading is free, and you don't need an account for most models.

If a model answers with nonsense or wanders off-topic while others work fine, its file may be missing its chat template, the instructions for how a conversation is laid out. Try the same model from another uploader.

How big a model can my Mac run?

The model has to fit into your Mac's memory (RAM) while it runs, with room to spare for macOS, your other apps and the conversation itself. Memory, not processor speed, decides which models you can use.

A practical guide for Q4_K_M files on Apple Silicon Macs:

Your Mac's memoryComfortableUpper limit
8 GB1–4B7–8B, with little else open
16 GB7–8B12–14B
24 GB12–14B20–24B
32 GB20–24B30–32B
64 GB and more30–32B70B

Presets & Config

Config holds the settings that shape the model's answers, such as Temperature (higher means more creative, lower means more focused). A set of settings is a preset; pick one from the list next to Config.

Ports

A port is the “door number” a program on your Mac listens on. You only need to change it if another program already uses one of Acopa's, for example when Acopa won't start, or Speak, Listen or a Local model reports that its port is in use. There's one setting, under Config → Ports, saved right away:

If a Speak, Listen or Local helper from an earlier Mipsy is still running (for example after a crash), Mipsy stops it by itself. If another program has the port, Mipsy tells you which one.

Handy shortcuts