Tutorial · tested 15 November 2026
apfel AI tutorial
Your first answer from the AI already on your Mac in 60 seconds. Then 11 jobs it does well, each one copy-paste ready with the real output, and an honest list of what it cannot do.
On this page: 15 sections
- Your first answer in 60 seconds
- 1. Ask your Mac about itself
- 2. Fix any text you copied
- 3. Read receipts, PDFs and scripts
- 4. Turn plain English into a shell command
- 5. Get JSON your scripts can trust
- 6. Automate your day: git, voice and ready-made scripts
- 7. Run your OpenAI code for free
- 8. Give it tools with MCP
- 9. Chat to test a prompt
- 10. Keep the server running in the background
- 11. Apps built on apfel
- Limits and honest answers
- When something fails
- Who made this and how it was tested
Your first answer in 60 seconds
You need an Apple Silicon Mac (M1 or newer) with macOS 26 Tahoe or later, and Apple Intelligence turned on in System Settings > Apple Intelligence & Siri. Check the first two in one line:
sw_vers -productVersion && uname -m
27.0.1
arm64A version of 26 or higher and arm64 mean you are ready. Install apfel with Homebrew. No Xcode, no account, no API key:
brew install apfelAsk your first question:
apfel "In one sentence: what can a small on-device language model do for me?"
A small on-device language model can help you perform tasks like text translation, summarization, and data analysis directly on your device.That answer came from Apple's model on your Mac. Nothing was sent to a server, and it cost nothing.
If it fails: ask apfel whether the model is ready:
apfel --model-info | grep -E 'available|context'
├ available: yes
├ context: 4096 tokensIf it says available: no, turn on Apple Intelligence in System Settings and wait until the model has finished downloading (the install guide says it is 3 to 4 GB). Your Mac's language and Siri's language must be the same supported language. apfel exits with code 5 while the model is unavailable.
Next: the jobs below. Each one starts with what you will have after two minutes.
1. Ask your Mac about itself
In 2 minutes you have: plain-English answers about your disk, CPU and memory, straight from the commands you already know.
When a terminal command prints a wall of numbers, I want a one-line answer, so I can act without reading a man page.
Pipe any command into apfel and say what you want to know:
df -h | apfel "which volume is fullest, one sentence"
/dev/disk3s1 is the fullest volume, with 630Gi used.ps aux | sort -k 3 -nr | head -5 | awk '{print $11, $3"%"}' | apfel "which app is using the most CPU, one sentence"
`/System/Library/CoreServices/RemoteManagement/screensharingd.bundle/Contents/MacOS/screensharingd` is using the most CPU.Keep the input small: head, awk and grep first, then apfel. The model reads only a few thousand words at once, fewer for code (see limits).
If it fails: some commands write to stderr, which a pipe does not carry. apfel tells you so: piped input was empty - if the command prints to stderr, try: command 2>&1 | apfel.
Next: the same trick works for git log, lsof, pmset -g batt, log files and anything else that prints text.
2. Fix any text you copied
In 2 minutes you have: a command that fixes the grammar of whatever is on your clipboard, in any app.
When I write a quick message in Slack, Mail or a browser, I want it cleaned up without opening another app, so I can paste it back in seconds.
Copy some text, then run the middle line. pbpaste reads the clipboard, pbcopy writes the result back:
printf 'can u send me the slides from yesterdays meeting i lost them' | pbcopy
pbpaste | apfel "Rewrite the text above with correct grammar and spelling. Reply with the rewritten text only." | pbcopy
pbpaste
Can you send me the slides from yesterday’s meeting? I lost them.Why "the text above": apfel puts piped text first and your instruction after it (source). With the short instruction "fix grammar and spelling, reply with the corrected text only", the model answered the message instead of fixing it and replied Could you let me know which meeting you're referring to?. Naming the text it should work on fixed that in our test.
If it fails: read the result before you send it. A small model changes meaning sometimes; when we asked it to translate this sentence to German, it turned "Can you send me" into "Can I send you".
Next: put the middle line into a shell alias or a Shortcuts "Run Shell Script" action and give it a keyboard shortcut.
3. Read receipts, PDFs and scripts
In 2 minutes you have: answers about an image, a scanned PDF or a script, read on your Mac with Apple's text recognition.
When a receipt, scan or unknown file lands in my Downloads, I want the one fact I need from it, so I can file it without opening it.
Attach a file with -f. We made a test receipt image (receipt.png) with these lines:
CAFE APFEL
2x Melange 9.80
1x Sachertorte 7.90
1x Apfelstrudel 6.50
TOTAL EUR 24.20
14.11.2026 21:14apfel -f receipt.png "What is the total? Just the amount."
24.20The same receipt saved as an image-only PDF works too, because apfel runs text recognition on scanned pages:
apfel -f receipt.pdf "What is the total? Just the amount."
24.20And any text file, for example a shell script:
apfel -f apfel-demos/gitsum "What does this script do? Two sentences."
This script summarizes recent Git activity by summarizing the last N commits, grouping related changes, and generating a concise report. It uses Apple Intelligence to format the output, and optionally copies the summary to the clipboard.You get that script in job 6. Attach several files with -f a.txt -f b.txt.
If it fails: exit code 4 means the file is too long for the model (see limits). Exit code 3 means Apple's safety filter blocked it; the file extraction guide suggests adding --permissive for that case.
4. Turn plain English into a shell command
In 2 minutes you have: the command you could not remember, printed bare so you can copy it.
When I forget the flags of find, du or tar, I want the command from a plain sentence, so I can stay in the terminal.
--code prints only the code, no explanation:
apfel --code "one find command that lists files larger than 100MB in my home folder"
find /Users/yourusername/home -type f -size +100MThe flags are right, but the model made up a folder. Your home folder is ~ (here: find ~ -type f -size +100M).
apfel --code "a python function that removes duplicates from a list but keeps the order"
def remove_duplicates_preserve_order(lst):
seen = set()
result = []
for item in lst:
if item not in seen:
seen.add(item)
result.append(item)
return resultRead every command before you run it. In our tests the model also produced wrong ones. Asked for "the 10 largest files in the current folder", it printed ls -lh | head -n 10, which lists the first 10 entries, not the largest. Asked to "show open ports", it suggested netstat -tuln | grep LISTEN, which uses Linux flags; on macOS it prints nothing at all. On a Mac, lsof -iTCP -sTCP:LISTEN -n -P lists them.
Next: the cmd demo script in job 6 wraps this and asks before it runs anything (-x) or copies the command (-c).
5. Get JSON your scripts can trust
In 2 minutes you have: structured data pulled out of messy text, as JSON that always matches your schema.
When I need names, numbers or dates out of emails and notes, I want fields, not prose, so I can feed them to jq, a spreadsheet or a script.
Save a JSON Schema as contact.schema.json:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"city": { "type": "string" },
"phone": { "type": "string" }
},
"required": ["name", "city", "phone"]
}Then pipe the text in with --schema. apfel constrains the model so the output is valid JSON for that schema:
echo "Hi, I am Maria Lopez from Vienna, call me on +43 660 1234567" | apfel --schema contact.schema.json "Extract the contact" | jq .
{
"name": "Maria Lopez",
"city": "Vienna",
"phone": "+43 660 1234567"
}The keys come back in the order your schema declares them.
For any answer as JSON with metadata, use -o json:
apfel -o json "Translate to German: apple" | jq -r .content
ApfelFor a whole list, use --batch: one JSON line per record in, one result line per record out, each record in a fresh session. Three product reviews in a text file:
cat reviews.txt
Love it, works offline and it is fast.
Crashes every time I open a PDF.
It is okay, it does the job.
jq -Rc '{custom_id: (input_line_number|tostring), prompt: ("Classify the sentiment of this review as positive, negative or neutral. Reply with one word. Review: " + .)}' reviews.txt | apfel --batch | jq -r '"\(.custom_id) \(.status) \(.content)"'
1 ok Positive
2 ok Negative
3 ok Neutral
apfel: batch: 3 records, 3 ok, 0 failedjq -R turns each line into a record; the last line is apfel's summary on stderr. A record that fails gets status: "error" and the batch goes on.
If it fails: apfel supports a subset of JSON Schema (objects, strings, enums, numbers, booleans, arrays, local $ref). An unsupported keyword such as pattern stops with exit code 2 and names it; the list is in the API compatibility doc.
6. Automate your day: git, voice and ready-made scripts
In 2 minutes you have: a summary of your recent work, a Mac that tells you out loud when a long job is done, and eight ready-made AI shell scripts.
When I switch tasks or wait for a build, I want small automations that explain and announce things, so I can stop watching the terminal.
Summarize what you did, from inside any git repository:
git log --oneline -10 | apfel "summarize what I have been working on, two sentences"
I've been updating star counts to 6,608 and refining ISO datetimes with timezone handling in the Article JSON-LD. Additionally, I've implemented the apfel AI tutorial and redesigned the pre-header with a centered line about the project.Let your Mac speak when something finishes. Pipe the answer into say, and put your long command in front of it with &&:
apfel "tell me cheerfully that my build just finished, one short sentence, no emoji" | sayThe test Mac had no sound output, so we recorded the speech to a file instead (| say -o build-done.aiff, 102,880 bytes of audio). The sentence it spoke was Your build is finished, and I'm glad you asked!.
apfel also ships eight demo scripts. Write them into a folder:
apfel --demos
apfel: wrote 9 demo files to /Users/arthurficial/work/apfel-i18n-video-2026-11-15/tut/apfel-demos
• cmd
• explain
• gitsum
• mac-narrator
• naming
• oneliner
• port
• wtdOne we liked in testing:
./apfel-demos/naming "function that retries HTTP requests with exponential backoff"
retryExponentialBackoff | exponential_retry_backoff | exponential delay retry
retryWithExponentialBackoff | exponential_retry_http_backoff | HTTP retry with delay
backoffRetryHTTP | exponential_http_retry | retry with exponential pauseNot every demo was good in our runs: oneliner "count unique IP addresses in access.log" ran into the length limit and printed a broken command, and explain added an error message that did not exist. The demo README lists all eight.
7. Run your OpenAI code for free
In 2 minutes you have: a local server that speaks the OpenAI Chat Completions API, so existing SDK code runs against your Mac instead of a paid cloud model.
When I prototype with the OpenAI SDK, I want a free local endpoint, so I can build and test without keys, bills or sending data away.
Start the server in one terminal tab:
apfel --serve
apfel server v1.18.0
├ endpoint: http://127.0.0.1:11434
├ model: apple-foundationmodel
├ cors: disabled
├ origin: localhost only (http://127.0.0.1, http://localhost, http://[::1])
├ token: none
├ health: public
├ max concurrent: 5
├ debug: off
└ ready
Endpoints:
POST http://127.0.0.1:11434/v1/chat/completions
GET http://127.0.0.1:11434/v1/models
GET http://127.0.0.1:11434/health
2026-11-15T13:39:31+0100 info Hummingbird: [HummingbirdCore] Server started and listening on 127.0.0.1:11434In a second tab, call it like OpenAI:
curl -s http://localhost:11434/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"apple-foundationmodel","messages":[{"role":"user","content":"Say hello to my terminal in five words."}]}' | jq -r '.choices[0].message.content'
Hello, terminal.The official OpenAI Python SDK works unchanged. Only the base URL and the model name differ. Save as hello.py:
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="unused")
reply = client.chat.completions.create(
model="apple-foundationmodel",
messages=[{"role": "user", "content": "Give me three names for a coffee shop run by robots."}],
)
print(reply.choices[0].message.content)python3 -m venv venv && ./venv/bin/pip -q install openai
./venv/bin/python hello.py
1. RoboBrew
2. CogCafé
3. Circuit SipThe server only listens on your own Mac (127.0.0.1) and refuses requests from web pages on other origins. To open it to your network, add a token: apfel --serve --host 0.0.0.0 --token-auto (server security guide).
If it fails: Connection refused means the server is not running. Embeddings and the old /v1/completions endpoint return HTTP 501, because the on-device model does not offer them.
Next: the maintainers document setups for VS Code Copilot (chat only), opencode, Zed and Node.js, Ruby, PHP and six more languages. We did not re-test those for this page.
8. Give it tools with MCP
In 2 minutes you have: the model reading a live web page and summarizing it, through a Model Context Protocol tool.
When the answer is on a web page, I want the model to fetch it itself, so I can get a summary without copying text around.
Install the apfel-mcp tools, which are built to fit the small context window:
brew install Arthur-Ficial/tap/apfel-mcpAttach one with --mcp and ask. -q hides the tool's raw output:
apfel -q --mcp $(which apfel-mcp-url-fetch) "Summarize https://apfel.franzai.com/ in 3 bullets"
- **Purpose**: apfel is a Swift 6.3 tool that wraps Apple’s on-device LLM (part of macOS 26’s Apple Intelligence) and exposes it via a CLI, HTTP server, and interactive chat with context management.
- **Features**: It handles terminal commands, JSON output, file attachments, real token counting, and context trimming (4,096 or 8,192 tokens depending on hardware), while converting OpenAI tool schemas to Apple’s native format.
- **Technical details**: Built using the FoundationModels framework, it runs on Apple Silicon’s Neural Engine and GPU without network or cloud dependencies, and is open-source under MIT license.The same package has apfel-mcp-ddg-search (web search), apfel-mcp-search-and-fetch and apfel-mcp-fs (read a local file). Any MCP server works: a local script path or an https:// URL.
Tools with several named arguments work too. Here is the calculator from the apfel repository (mcp/calculator/server.py): the model calls multiply with both arguments, apfel runs it and the model answers with the result:
apfel --mcp ./server.py "What is 15 times 27?"
mcp: /Users/arthurficial/work/apfel-i18n-video-2026-11-15/tut/./server.py - add, subtract, multiply, divide, sqrt, power, round_number
tool: multiply({"a": 15, "b": 27}) = 405
15 times 27 is 405.The tool: line is apfel showing you the call it ran. Before apfel 1.18.0 the model did not see the argument names and guessed them, so a call like this failed (issue #555, fixed in pull request #556). If you see invalid arguments here, update with brew upgrade apfel.
9. Chat to test a prompt
In 2 minutes you have: a conversation in the terminal that remembers what you said earlier.
When I am shaping a prompt for a script, I want to try a few turns quickly, so I can see how the model reacts before I automate it.
apfel --chat
Apple Intelligence · on-device LLM · apfel v1.18.0
────────────────────────────────────────────────────────
Type 'quit' to exit.
you› My name is Franz. I live in Vienna.
ai› Hello, Franz. It's nice to meet you. I'm here to help with any questions or tasks you might have. How can I assist you today?
you› Suggest one thing I could do there this weekend. One sentence.
ai› You could visit the Kunsthistorisches Museum to explore its impressive collection of art and artifacts.
you› What is my name?
ai› Your name is Franz.
you› quit
Goodbye.Add a persona with -s, for example apfel --chat -s "You are a patient Python tutor". When a long chat outgrows the context window, apfel drops the oldest turns by default; the context guide explains the other strategies. For a window with buttons, see apfel-chat.
10. Keep the server running in the background
In 2 minutes you have: the OpenAI-compatible server starting by itself at login, always ready on port 11434.
When tools on my Mac use the local endpoint every day, I want it always on, so I can stop starting it by hand.
brew services start apfel
==> Successfully started `apfel` (label: sh.brew.apfel)
curl -s http://127.0.0.1:11434/health | jq -c '{status, model_available, context_window}'
{"status":"ok","model_available":true,"context_window":4096}
brew services stop apfel
Stopping `apfel`... (might take a while)
==> Successfully stopped `apfel` (label: sh.brew.apfel)Settings such as the port, a token or MCP servers are environment variables, for example APFEL_PORT=8080 brew services start apfel. All of them are listed in the background service guide.
11. Apps built on apfel
In 2 minutes you have: the same on-device model in a window, a menu bar or a hotkey, if you prefer apps over the terminal.
These come from the same maintainers (the "apfel tree" in the README). We checked that each install name exists in Homebrew on 15 November 2026; we did not test the apps for this page.
| App | What it does | Install |
|---|---|---|
| apfel-chat | Chat app with streaming answers, speech and image analysis | brew install Arthur-Ficial/tap/apfel-chat |
| apfel-clip | Menu bar actions on the clipboard: summarize, translate, rewrite | brew install Arthur-Ficial/tap/apfel-clip |
| apfel-quick | Press a key, ask, get the answer, dismiss | brew install Arthur-Ficial/tap/apfel-quick |
| apfelpad | Notepad where the AI is a formula you put in a cell | brew install Arthur-Ficial/tap/apfelpad |
| apfel-mcp | MCP tools sized for the small window (job 8) | brew install Arthur-Ficial/tap/apfel-mcp |
| apfel-run | apfel with a saved config and a list of MCP servers | brew install Arthur-Ficial/tap/apfel-run |
| apfel-tag | Tags, topics and emotions for any text you pipe in | brew install Arthur-Ficial/tap/apfel-tag |
| apfel-gui | Debug window: requests, MCP messages, speech | brew install Arthur-Ficial/tap/apfel-gui |
Limits and honest answers
apfel gives you Apple's on-device model. The README puts it at about 3 billion parameters, much smaller than the cloud models behind ChatGPT or Claude. It is good at short, focused text jobs. These are the limits we hit or that the documentation states.
The context window is small. Question plus answer must fit into 4,096 tokens on macOS 26 and on M1 and M2 Macs, or 8,192 tokens on M3 or newer Macs with 12 GB or more running macOS 27 (README). apfel --model-info shows yours. apfel's own README is too long for it. Count before you send:
apfel --count-tokens -f README.md "summarize in 3 bullets"
8272/3584 tokens (over budget)
prompt=7, README.md=8258
apfel -f README.md "summarize in 3 bullets"; echo "exit code: $?"
error: [context overflow] Input exceeds the model's context window: the input is 8264 tokens, the window is 4096 tokens. Shorten the conversation history.
exit code: 4The 3,584 is the 4,096 window minus 512 tokens kept free for the answer. The README has about 3,000 words, but Markdown and code cost many tokens per word. Feed long files in parts (head -c 6000 file), one section at a time.
It does not know today's date. It made one up:
apfel "What is today's date?"
Today's date is October 27, 2024.
apfel -s "Today is $(date '+%B %d, %Y')." "What is today's date? One sentence."
Today's date is November 15, 2026.Give it any fact it needs in the prompt. It has no internet unless you attach an MCP tool.
It is wrong sometimes, with confidence. You saw it above: wrong shell commands in job 4, a translation that flipped the meaning in job 2. Check anything that matters.
Apple's safety filter can block harmless text. apfel then stops with exit code 3 and the message The request was blocked by Apple's safety guardrails. Rephrase, or add --permissive for creative writing and documents; the guardrails doc explains what it changes. We did not hit a block in the runs for this page.
Answers differ every run. These are real outputs from one run each. Yours will be worded differently. Use --temperature 0 for more repeatable answers; apfel does not promise identical output across runs or macOS updates (stability policy).
Speed: most answers in our runs came back in 1 to 2 seconds. The web page summary with an MCP tool took 8 seconds.
Requirements are strict: Apple Silicon only, macOS 26 or newer, Apple Intelligence on, and one of the 15 languages --model-info lists. Intel Macs cannot run it.
When something fails
apfel reports problems with an exit code, so scripts can react. Check it with echo $? right after the command.
| Exit code or error | Meaning | What to do |
|---|---|---|
2 |
Wrong flag or option | Flags go before the prompt; apfel --help lists them |
3 |
Apple's safety filter blocked the request | Rephrase, or add --permissive |
4 |
Input too long for the context window | Send less text; check with apfel --count-tokens |
5 |
Model unavailable | Turn on Apple Intelligence, wait for the download, match Mac and Siri language |
6 |
The model is busy or rate limited | Wait and run it again, or add --retry |
Connection refused |
No server on port 11434 | Start apfel --serve or brew services start apfel |
| HTTP 501 | Endpoint the on-device model does not offer (embeddings, /v1/completions) |
Use /v1/chat/completions |
piped input was empty |
The command wrote to stderr | command 2>&1 \| apfel "..." |
Still stuck? Search or open an issue on GitHub.
Who made this and how it was tested
apfel is free and open source (MIT license), a franzai project by Franz Enzenhofer. It is maintained with Arthur Ficial, Franz's AI assistant, which also wrote this tutorial. Because the makers of apfel wrote this page, we listed every failure we saw instead of leaving them out.
How we tested: on 15 November 2026 we ran every command on this page on a MacBook Air M2 (24 GB) with macOS 27.0.1 (build 26A434). We used the signed apfel 1.18.0 binary from the GitHub release (the same file the Homebrew tap installs), inside a real terminal session, and copied the output unchanged. The first version of this page (14 November 2026, apfel 1.16.0) showed the multi-argument tool bug in job 8; 1.18.0 fixes it, so we reran every command for this version. Where the first output was wrong, we kept the wrong output on the page and said so. The only reruns were to find answers that needed no edit: one web page summary contained a long dash, which this site does not print, so we ran it again and kept the third run. The speech example was checked by writing the audio to a file, because the test Mac had no sound output. The demo scripts were written by apfel --demos from apfel 1.18.0.
What others wrote about apfel: the Show HN post (3 April 2026, 743 points), a guide by Better Stack, an article by GIGAZINE and a hands-on review on danilchenko.dev.
Sources: the apfel README, the CLI reference, the install guide, the demo scripts, apfel vs Apple's fm and the issue tracker, read on 15 November 2026.