Alfred is a lightweight, menu-bar utility agent for macOS. Your seamless, silent helper for file conversion, organization, renaming, and AI-powered tasks — all from the menu bar.
- Invisible: Lives in the menu bar. Out of sight until needed.
- Fast: Native SwiftUI frontend, Python backend — instant startup.
- Private: Uses local AI by default (Ollama), or connect to cloud providers (OpenAI, Anthropic, Google) with your own API keys.
- Self-contained: Ships with a full embedded Python runtime. No Python, Homebrew, or pip required to run.
- Download
Alfred.app.zipfrom the Releases page. - Unzip it — you'll see
Alfred.appandinstall.shside by side. - Open Terminal,
cdto the unzipped folder, and run:bash install.sh
- Alfred is now in
/Applications. Double-click to launch — it appears in your menu bar.
Why the install script? Alfred is not signed with a paid Apple Developer certificate, so macOS Gatekeeper will show "Alfred is damaged" if you double-click it directly.
install.shremoves that restriction in one step. No password required.
No Python, no Homebrew, no pip. Everything is bundled inside the app.
Requirements (developer machine only, not needed by end users):
- macOS 13 or later (Apple Silicon — ARM64)
- Xcode Command Line Tools:
xcode-select --install - Internet access (first run downloads ~45 MB standalone Python)
Intel Mac users:
build.shdefaults to theaarch64(Apple Silicon) Python build. Edit thePYTHON_ARCHvariable at the top ofbuild.shtox86_64-apple-darwinbefore running.
# 1. Clone
git clone https://github.com/yourusername/Alfred.git
cd Alfred
# 2. (Optional) configure AI provider
cp cli/.env.example cli/.env
# Edit cli/.env — see AI Configuration below
# 3. Build everything (downloads Python, installs deps, builds Swift app)
./build.sh
# 4. Launch
open swift-alfred/Alfred.appbuild.sh handles everything automatically:
- Downloads a relocatable Python 3.13 runtime (cached after first run)
- Creates a venv inside
Alfred.appand installs all Python dependencies - Copies
alfred.pyinto the bundle - Builds the Swift app
- The result is a fully self-contained
Alfred.app— zip it up and share it
For subsequent builds after code changes:
./build.sh # incremental (uses cached Python)
./build.sh --clean # full rebuild from scratchAlfred uses LiteLLM to support 100+ AI providers. Edit cli/.env before building:
# Local AI (default — private, no API key needed)
AI_PROVIDER=ollama
AI_MODEL=qwen3:4b
OLLAMA_API_BASE=http://localhost:11434
# OpenAI
AI_PROVIDER=openai
AI_MODEL=gpt-5-mini # or gpt-5.2 for flagship
OPENAI_API_KEY=sk-...
# Anthropic Claude
AI_PROVIDER=anthropic
AI_MODEL=claude-sonnet-4-6
ANTHROPIC_API_KEY=sk-ant-...
# Google Gemini
AI_PROVIDER=google
AI_MODEL=gemini-2.5-pro # or gemini-3-pro-preview (preview)
GOOGLE_API_KEY=your-google-api-key-hereFor Ollama (local AI): install from ollama.com, then ollama pull qwen3:4b.
See AI_PROVIDERS.md for full details.
Alfred ships with Python libraries that handle common conversions natively. Optional tools (ffmpeg, pandoc) are used when available and extend the format list further.
All formats interconvertible with no external tools:
| From | To |
|---|---|
| PNG | JPG, WebP, BMP, GIF, TIFF, ICO, PDF |
| JPG | PNG, WebP, BMP, GIF, TIFF, ICO, PDF |
| WebP | PNG, JPG, BMP, GIF |
| HEIC/HEIF | JPG, PNG |
| GIF | PNG, JPG, WebP |
| BMP, TIFF | PNG, JPG |
Common audio conversions with no ffmpeg required:
| Format | Converts to |
|---|---|
| MP3 | WAV, FLAC, OGG |
| WAV | MP3, FLAC, OGG, AAC, M4A |
| FLAC | MP3, WAV, OGG |
| OGG | MP3, WAV |
| M4A, AAC | MP3, WAV |
Install ffmpeg for video conversion and extended audio formats:
alfred install ffmpeg
No pandoc or system tools required:
| From | To |
|---|---|
| Markdown (.md) | HTML, PDF, DOCX, EPUB |
| Plain text (.txt) | HTML, PDF, DOCX |
| HTML | PDF, DOCX, EPUB |
| DOCX | PDF, TXT |
Install pandoc for extended document support:
alfred install pandoc
All data conversions are pure Python, no external tools:
| From | To |
|---|---|
| JSON | CSV, YAML, XLSX, TOML |
| CSV | JSON, XLSX |
| YAML | JSON |
| XLSX | CSV, JSON |
| TOML | JSON |
Organize files by category or natural language instructions:
- "Move all screenshots from last week to a Screenshots folder"
- "Sort by file type"
- Vision-capable: analyzes image content to organize photos by subject
Renames files based on content. For images, uses vision models to describe what's in the photo. For documents, reads the content.
Summarize any text file, document, or code file in 3 bullet points.
Natural-language shell commands — type what you want done, Alfred generates and runs the code.
Alfred also works as a standalone CLI (inside the venv):
cd cli
source venv/bin/activate
# Convert files
python alfred.py convert photo.heic jpg
python alfred.py convert document.md pdf
python alfred.py convert data.json yaml
python alfred.py convert spreadsheet.xlsx csv
# Organize
python alfred.py organize ~/Downloads
python alfred.py organize ~/Downloads --instructions "group by year" --confirm
# Rename
python alfred.py rename *.jpg --confirm
# Summarize
python alfred.py summarize report.pdf
# AI command
python alfred.py ask "compress all images in this folder to 80% quality" ~/Photos| Layer | Technology |
|---|---|
| Frontend | SwiftUI — native macOS menu bar app (NSStatusItem) |
| Backend | Python 3.13 — Typer CLI + Rich output |
| AI | LiteLLM — unified interface for 100+ LLM providers |
| Python runtime | python-build-standalone — embedded in the .app |
| Images | Pillow + pillow-heif |
| Audio | pydub |
| Documents | fpdf2, python-docx, markdown, ebooklib |
| Data | PyYAML, openpyxl, toml |
| Optional tools | ffmpeg (video/audio), pandoc (advanced docs) |
Alfred/
├── build.sh # Build script — assembles self-contained Alfred.app
├── cli/
│ ├── alfred.py # Python CLI backend (all conversion + AI logic)
│ ├── requirements.txt # Python dependencies (bundled into .app by build.sh)
│ ├── .env.example # AI provider configuration template
│ └── tests/ # Test suite (192 tests)
├── swift-alfred/
│ ├── Sources/Alfred/
│ │ ├── AlfredApp.swift # App entry point, menu bar NSStatusItem
│ │ └── AlfredView.swift # SwiftUI UI — uses bundle-relative Python paths
│ ├── Alfred.app/ # Pre-built app bundle (populated by build.sh)
│ └── Package.swift
├── AI_PROVIDERS.md
└── EXAMPLES_AI_SWITCHING.md
cd cli
source venv/bin/activate
pytest tests/ -v
# 192 testsAfter running ./build.sh, the .app is fully self-contained:
# Zip for sharing
zip -r Alfred.zip swift-alfred/Alfred.app
# Or copy to Applications
cp -R swift-alfred/Alfred.app /Applications/Alfred.appFor notarization (App Store / Gatekeeper signing), sign all bundled .so files and the app:
find swift-alfred/Alfred.app -name "*.so" -o -name "*.dylib" | while read f; do
codesign --force --sign "Developer ID Application: Your Name (TEAMID)" "$f"
done
codesign --force --deep --sign "Developer ID Application: Your Name (TEAMID)" swift-alfred/Alfred.app
xcrun notarytool submit Alfred.zip --apple-id you@example.com --team-id TEAMID --wait
xcrun stapler staple swift-alfred/Alfred.app- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Run tests:
cd cli && pytest tests/ - Commit:
git commit -s -m "Add my feature" - Push and open a Pull Request
- AI_PROVIDERS.md — Ollama, OpenAI, Anthropic, Google setup
- EXAMPLES_AI_SWITCHING.md — provider switching examples
- AGENTS.md — guidelines for AI agents working on this project
MIT License — see LICENSE.