tai/research/shell-multiplexer-auto-attach/zsh-org-mla-2009-msg00989-command-not-found-handler.md

zsh-users mailing list: minimal command_not_found_handler example (Peter Stephenson, 2009)

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	shell-multiplexer-auto-attach
Document type	Source Dossier
Tier	1
Source title	Zsh Mailing List Archive (zsh-users, 2009, msg00989)
Source URL	https://zsh.org/mla/users/2009/msg00989.html
Source publisher / author	Peter Stephenson, via the zsh-users mailing list (zsh.org)
Source type	forum thread
Source date (published)	2009 (exact date not stated in the search result)
Date researched	2026-10-10
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	web search synthesis
Confidence	Medium
Status	Active

Summary

A much simpler, minimal command_not_found_handler example from a second zsh core contributor: checks whether the missing command equals a specific name (foo), prints a message and returns 0 if so, and otherwise returns 127 — the return code that reproduces zsh's normal "command not found" message and exit status for every other missing command.

Key findings

• Returning 127 from the handler for anything it doesn't want to specially handle is the documented way to fall through to zsh's normal "command not found" behavior and exit status, rather than silently swallowing the error.
• This example is structurally the simplest possible command_not_found_handler: no autoload, no dynamic loading, just a plain conditional and a return code — directly comparable in shape to what tai.py actually needed.

Pros / strengths

• A minimal, directly comparable example (vs. the more advanced 2015 autoload-based one) that maps cleanly onto tai's own simple "forward everything to the tai binary" use case.

Cons / limitations / caveats

• tai's own handler doesn't need the 127-fallthrough behavior this example demonstrates, since it unconditionally forwards every missing command to the tai binary rather than special-casing one and falling through for the rest — noted here as a deliberate difference, not an oversight.

Relevance to tai

Reinforces (independently of the 2015 example) that command_not_found_handler is just a plain zsh function, confirming there's no hidden registration step ZSH_NOTFOUND_BLOCK would need to account for beyond the function definition itself.

Changelog

Date	Change
2026-10-10	Initial dossier created.