NAME

flashcat

— a local AI assistant for your Mac terminal. Private. Offline. Yours.

PDF · Word · Excel / LM Studio · Ollama · llama.cpp / Gemma 4 / Apple Silicon / free & open source

$ install flashcat ▶ watch it work

This is Flash. Go on, pet him.

SYNOPSIS

flashcat [--continue] [--model name]
flashcat "which PDF is the newest invoice?"
cat log | flashcat "why?"

Pick a question and watch Flashcat answer it:

DESCRIPTION

Flashcat works in the folder you start it in. Ask in plain language – it reads, writes and searches for you, and asks before it changes anything.

.md

Files

List, read, search, create and change text files. Create Word and PDF documents, rename and move files – many at once, undone in one step.

PDF

Documents

Reads PDF, Word and Excel – even scanned PDFs and images, through the text recognition built into macOS. Searches them for several words at once, so it finds a topic even when the document words it differently.

JPG

Images

Describes and analyzes the pictures in your folder – and screenshots you paste with Ctrl+V.

</>

Coding

Reads, explains, writes and fixes code, and runs your tests and scripts in a sandbox to check its work – you confirm every change and every command. /plan makes it plan first and change nothing; with /test your tests run by themselves after every change. It can't match the big frontier models in the cloud, but it does a solid job on simple tasks, free and fully on your Mac.

WWW

Web

Searches the web (DuckDuckGo) and reads web pages – only after you say yes.

❯_

Terminal

Answers stream live with Markdown, tables and highlighted code. Paste screenshots with Ctrl+V (they show up as [Image #1]; ⌘V works too in terminals like Hyper), drag images in, or ask once without a chat: cat log | flashcat "why?" Long chats are summarized by themselves, /model switches the model, and /command saves your own commands.

SAFETY

Enforced by code,
not by the model.

WHAT FLASHCAT CAN SEE
~/
├── Documents/ ← you start Flashcat here
│ ├── invoices/ ✓ readable
│ └── notes.md ✓ readable
├── Library/ ✕ locked
├── .ssh/ ✕ locked · private keys
└── .zshrc ✕ locked · hidden file
  1. [Y/N] every change asks firstYou see a preview – or the full command – before you answer Y. The old version is backed up, and /undo reverts the last change.
  2. [sandbox] commands stay in their boxOnly the start folder and its subfolders. Commands run in a sandbox: no internet, they can only write inside the folder, and nothing they start keeps running. Git hooks they sneak in are caught and undone. Only an image you drag or paste in yourself comes from outside.
  3. [offline] stays on your MacThe model runs locally in LM Studio, Ollama or llama.cpp. Nothing leaves your computer unless you allow a web request – and you always see the full address first.

All details: Safety in the README and SECURITY.md. Flashcat is powered by a language model – please double-check important results.

REQUIREMENTS

How much memory does your Mac have?

0 GB8.4 GB left for macOS and your apps24 GB
okayClose all other apps while you use Flashcat. Otherwise macOS moves parts of the model to disk and answers become much slower.

Built and tuned on a MacBook Air M5 with 24 GB. Only the M5 is tested so far – older M chips should work too, but answers will be slower. Tried it on another Mac? Let me know how it runs.

Short on memory? llama.cpp (brew install llama.cpp) is the leanest way to run the model: no app, only the bare model server, which Flashcat starts and stops itself. On my MacBook Air M5 it needed about 1 GB less memory than through LM Studio and answered a bit faster (one short measurement, same model and questions). Choose it with flashcat --backend llamacpp. Already downloaded Gemma 4 in LM Studio? llama.cpp runs those files directly, and Ollama can use them too – no second download.

INSTALL

Three steps. No account, no cloud.

  1. 1

    Flashcat needs a program that runs the model: llama.cpp (recommended – the fastest, needs the least memory), LM Studio / LM Studio Bionic or Ollama. Nothing installed yet? With Homebrew, the installer offers to install llama.cpp for you.

  2. 2

    Run this in the terminal:

    curl --proto '=https' --tlsv1.2 -fsSL https://github.com/TomTomsen765/flashcat/releases/latest/download/install.sh | bash

    The installer downloads the default model, Gemma 4 (about 15.6 GB). With llama.cpp it asks first, so you can use a model of your own instead.

  3. 3

    Go to a folder and start it: cd ~/Documents && flashcat

You need a Mac with Apple Silicon and at least 24 GB of memory, plus Python from Apple's free command line tools – most Macs already have them, and if not, the installer tells you how to get them (xcode-select --install). More than one of them installed? The installer asks once which one to use (change it with flashcat --backend). I use Flashcat with llama.cpp now, because it is fast and leaves the most memory free; before that I used it with LM Studio for a long time, and everything runs great there. llama.cpp is still new in Flashcat, and Ollama still needs to be tested properly – let me know how it goes.

Prefer to read the code before running it? Here is how. Update later with flashcat --update (Homebrew: brew upgrade flashcat) – you only get published releases that passed the automated safety tests, and a published release cannot be changed afterwards.

NAMED AFTER

Flash, my cat.
Currently asleep.