What’s New in 1.0.2 (2026-04-21)

Version 1.0.2 is a milestone release. It completely drops the old, complex workflow development model in favour of modern Python practices: write pure functions, run them locally, and they work in Alfred out of the box — no adapters, no scaffolding, no glue code. Combined with uvx for zero-install deployment, the gap between a working Python function and a shipping Alfred workflow has never been smaller.

Project Background

The official Alfred Python library had not been updated for years and only supported Python 2.7 — a version that reached end-of-life in January 2020 and was removed from macOS in 2021. This left every workflow built on that library broken on modern Macs. The library also suffered from heavy coupling: it bundled HTTP clients, caching, and other concerns that belong in dedicated third-party packages, producing layers of workarounds on top of outdated code.

At the same time, I personally maintain more than a dozen Alfred workflows across different domains. Early on, each project contained large amounts of boilerplate unrelated to business logic — Alfred integration glue, test scaffolding, and meta-programming code duplicated across every repo. Extracting that into a reusable framework became the obvious next step.

afwf provides:

• A clean Python data model for Alfred’s Script Filter JSON protocol, built on Pydantic.

• A fluent Item API with action helpers (open_url, run_script, send_notification, …) that wire directly to Alfred’s Conditional widget.

• Optional fuzzy-matching (afwf[fuzzy]) and disk-caching (afwf[cache]) extras.

• A deployment pattern — publish to PyPI, expose via fire CLI, invoke with uvx — that eliminates dependency management on the end-user machine.

• Best practices for development, testing, and release derived from building the official AWS internal Alfred Workflow (one of the largest Alfred workflow codebases in existence).

The library also ships ~50 bundled PNG icons commonly used in productivity workflows. Preview all icons.

Core Modules

import afwf.api as afwf

q = afwf.Query.from_str("  hello   world  ")
q.trimmed_parts   # ['hello', 'world']
q.n_trimmed_parts # 2

parser = afwf.QueryParser.from_delimiter([" ", "/"])
q = parser.parse("foo/bar baz")
q.trimmed_parts   # ['foo', 'bar', 'baz']

import afwf.api as afwf

@afwf.log_error()
def main(query: str) -> afwf.ScriptFilter:
    ...

# Custom log file and size limit
@afwf.log_error(log_file="~/.alfred-afwf/search.log", max_bytes=200_000)
def main(query: str) -> afwf.ScriptFilter:
    ...

Quickstart

A minimal Script Filter handler:

import afwf.api as afwf

@afwf.log_error()
def main(query: str) -> afwf.ScriptFilter:
    q = afwf.Query.from_str(query)
    sf = afwf.ScriptFilter()
    item = afwf.Item(title="Hello", subtitle=f"You typed: {q.raw}")
    item.open_url(url="https://example.com")
    sf.items.append(item)
    return sf

if __name__ == "__main__":
    import fire
    fire.Fire({"search": lambda query="": main(query).send_feedback()})

Deployment Pattern (Best Practice)

Publish your workflow logic as a Python package on PyPI, expose it as a CLI using fire, then invoke it from Alfred’s Script Filter via uvx:

# Development / local
~/Documents/GitHub/my-workflow-project/.venv/bin/my-workflow search --query '{query}'

# Production (no install required on end-user machine)
~/.local/bin/uvx --from my-workflow==1.0.0 my-workflow search --query '{query}'

The afwf-examples CLI bundled in this repo demonstrates all built-in example handlers:

afwf-examples search-bookmarks --query 'git'
afwf-examples open-file
afwf-examples read-file
afwf-examples write-file --query 'hello'
afwf-examples view-settings
afwf-examples set-settings --query 'theme'
afwf-examples memoize --query 'test'

AI-Assisted Development (Claude Code Agent Skill)

This repo ships a Claude Code Agent Skill under .claude/skills/afwf/.

The Skill is a self-contained reference guide written for AI assistants. Hand it to any AI that supports the Skill mechanism (such as Claude Code) and the AI instantly knows how to build Alfred workflows with afwf, covering:

• How to write a Script Filter handler (main(query) → ScriptFilter)

• Mapping CLI entry points (fire.Fire) to Alfred’s Script field

• Every Item action method (open_url, run_script, send_notification, …)

• Query parsing, fuzzy matching (afwf[fuzzy]), and disk caching (afwf[cache])

• The two-phase write-action pattern (run_script + send_notification)

• Unit testing patterns — no Alfred required, plain pytest

• Local dev and uvx production deployment

Directory layout:

.claude/skills/afwf/
├── SKILL.md                          # Main Skill file — the AI reference manual
└── ref/
    ├── script-filter-json-format.md  # Alfred Script Filter JSON protocol spec
    └── script-filter-input.md        # Alfred Script Filter input format reference

Activating in Claude Code:

Type /afwf in the conversation. Claude Code loads the Skill and from that point on you can describe what you want in plain English — the AI will generate complete, ready-to-run afwf code following best practices.

You:    /afwf Write a Script Filter that fuzzy-searches a hardcoded list of bookmarks
Claude: [Skill loaded → generates complete afwf-idiomatic code]

Install

afwf is released on PyPI, so all you need is:

$ pip install afwf

To upgrade to latest version:

$ pip install --upgrade afwf

Optional extras:

# Fuzzy matching (rapidfuzz)
$ pip install "afwf[fuzzy]"

# Disk caching (diskcache)
$ pip install "afwf[cache]"

# Both
$ pip install "afwf[fuzzy,cache]"