omppu

Apple Intelligence for your terminal. (Finnish: omppu = apple)

Ask questions in plain English. omppu answers from general knowledge, your project's README and git history, or by running shell commands — whichever is appropriate. Everything runs on-device via Apple Intelligence; no API keys, no cloud, no billing.

$ omppu "what does exit code 137 mean?"
Exit code 137 means the process was killed by SIGKILL (signal 9),
typically by the OOM killer or a manual kill -9.

$ omppu "what tools does this project install?"
The project installs: direnv, pyenv, rbenv, mise, starship,
postgresql@17, openssl@3, make, fzf (via Homebrew), and Oh My Zsh.

$ omppu "how much disk space is this directory using?"
740K

$ omppu "what's my machine's uptime?"
$ uptime
Run this? [y/N] y
Your machine has been up for 3 days, 14 hours.

$ git diff -- src/deploy.rb | omppu "summarise these changes"
Adds a retry loop to the deploy task and bumps the timeout to 60s.

Requirements

• Apple Silicon Mac running macOS 26 Tahoe or newer
• Apple Intelligence enabled — how to enable it
• apfel — the CLI that exposes Apple's on-device model

Installation

Step 1 — install apfel

brew tap Arthur-Ficial/tap
brew install Arthur-Ficial/tap/apfel

Verify it works:

apfel "hello"

If that returns a response, you're good. If not, check that Apple Intelligence is enabled in System Settings → Apple Intelligence & Siri.

See apfel's install docs for troubleshooting.

Step 2 — install omppu

Option A — download directly:

curl -fsSL https://raw.githubusercontent.com/randomm/omppu/main/omppu -o ~/bin/omppu
chmod +x ~/bin/omppu

Make sure ~/bin is in your PATH. If it isn't, add this to ~/.zshrc:

export PATH="$HOME/bin:$PATH"

Then reload: source ~/.zshrc

Option B — clone and symlink:

git clone https://github.com/randomm/omppu.git ~/.omppu
mkdir -p ~/bin
ln -s ~/.omppu/omppu ~/bin/omppu

Step 3 — try it

omppu "what does exit code 1 mean?"

Usage

omppu [OPTIONS] "your question"
command | omppu "interpret this"

Options:
  -r, --run    Force command mode — skip direct-answer attempt, run a command first
  -c, --copy   Copy the answer to clipboard (uses pbcopy)
  -h, --help   Show help

Examples

# General knowledge — answered directly, no commands run
omppu "what does SIGTERM do?"
omppu "what's the difference between 2>&1 and 2>/dev/null?"

# Project context — reads README and git log automatically
omppu "describe this project"
omppu "what shell framework does this project use?"
omppu "summarize the recent git history"

# Live system data — generates and runs the right command
omppu "how much memory is available?"
omppu "what's using the most disk space here?"
omppu "which processes are listening on port 5432?"

# Force command mode (useful when auto-detection gets it wrong)
omppu -r "why is my machine running slow?"

# Pipe any text through — input must fit in ~4096 tokens (~3000 words)
cat error.log | omppu "what's going wrong?"
git diff -- path/to/file.rb | omppu "summarise these changes"  # scope to one file for large repos
curl -s api.example.com/status | omppu "is anything degraded?"

# Copy answer to clipboard
omppu -c "write a one-line description of this project"

Command approval and the whitelist

When omppu needs to run a shell command, it checks whether that command is whitelisted:

• Whitelisted → runs automatically, no prompt.
• Not whitelisted → prints the command in yellow and asks Run this? [y/N].

The built-in defaults cover common read-only commands: git, ls, du, df, ps, pwd, cat, find, grep, wc, head, tail, echo, date, uname, sw_vers, system_profiler

Adding your own whitelist patterns

Create ~/.config/apfel/whitelist and add one Extended Regular Expression per line:

mkdir -p ~/.config/apfel
cat > ~/.config/apfel/whitelist << 'EOF'
# Lines starting with # are comments and are ignored.
# Blank lines are also ignored.

# Match any brew command
^brew

# Match docker ps (but not docker run, docker exec, etc.)
^docker ps

# Match any npm or npx command
^np[mx]
EOF

What gets matched: Only the first command in a pipeline is checked. For du -sh . | sort -rh | head, only du -sh . is matched against the whitelist. This means whitelisting ^du allows du … | anything to run automatically.

Pattern tips:

• ^brew matches brew install, brew update, brew list, etc. (anything starting with brew)
• ^brew list$ matches only brew list with no arguments
• Patterns are ERE, so ., *, +, [], (), | have special meaning — escape with \ if you want them literal

What omppu does

• Answers general programming questions from its built-in knowledge
• Reads the project README and recent git log to answer project-specific questions
• Generates and runs shell commands for questions that need live data, up to 5 rounds per question
• Pipes any stdin through to Apple Intelligence for interpretation

What omppu does not do

• Not a coding assistant — for writing or editing code, use Claude Code or similar.
• Not always accurate — Apple Intelligence is a small on-device model. It can hallucinate. Treat answers as a helpful starting point, not ground truth.
• Not great with large inputs — Apple Intelligence has a 4096-token context window (~3000 words). Piping a full git diff across many files will hit this limit and fail with a context overflow error. Scope your input: git diff -- path/to/file or head -100 big.log.
• Not streaming — you wait for the full answer.
• macOS only — depends on Apple Intelligence, which is Apple Silicon + macOS 26 Tahoe+.

How it works

For each question, omppu makes at most a handful of calls to Apple Intelligence:

1. Answer or signal — sends your question with local context (current directory, README if present, git log if the question is about history). The model either answers directly or signals NEED_CMD to indicate it needs live data.
2. Generate command — if live data is needed, asks the model for the right shell command to run.
3. Interpret — runs the command (with whitelist check / approval prompt) and sends the output back for interpretation. Repeats up to 5 times if multiple commands are needed.

Piped input (cat file | omppu "...") skips steps 1–2 and goes straight to interpretation.

Credits

omppu is powered by apfel by Arthur-Ficial, which wraps Apple's on-device FoundationModels framework. Without apfel, omppu is just a shell script with nowhere to send its questions.

License

MIT