These examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them.
Safety and completeness boundaries
xexplicitly bypasses approvals and sandboxing;xidoes not. The bypass is a high-trust, separately isolated option, not a prerequisite for loading the environment marker._codex_app_server_fork_latestand_codex_app_server_fork_compact_latestare guard stubs returning 64. A compatible app-server implementation is required before fork/compact helpers can work.agent_chain,ghost-save, andaicmare lazy-loader shapes, not bundled implementations of those workflows. Check their dependencies instead of treating function presence as proof.pkskandkskare destructive process-cleanup examples. Their broad process matching and process-group signals can stop unrelated work; inspect targets and ownership before adapting them.- Prompt Builder handoff preserves argument boundaries only if the receiving helper also avoids reparsing the prompt as shell code.
zsh/functions/codex-launch-and-prompt-builder.zsh
# Focused Codex + Prompt Builder helper snippets.
# These are excerpts for workshop discussion, not a full private shell config.
unalias x 2>/dev/null
x() {
codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \
--dangerously-bypass-approvals-and-sandbox "$@"
}
xi() {
codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' "$@"
}
_codex_app_server_fork_latest() {
echo "_codex_app_server_fork_latest is not bundled in this package." >&2
echo "Install the local Codex app-server helper or replace this guard with a reviewed snippet." >&2
return 64
}
_codex_app_server_fork_compact_latest() {
echo "_codex_app_server_fork_compact_latest is not bundled in this package." >&2
echo "Install the local Codex app-server compact helper or replace this guard with a reviewed snippet." >&2
return 64
}
_codex_cmux_current_session_id() {
local helper="$HOME/.codex/hooks/cmux-codex-session-registry.py"
[[ -n "${CODEX_FORK_SESSION_ID:-}" ]] && {
print -r -- "$CODEX_FORK_SESSION_ID"
return 0
}
local surface="${CMUX_SURFACE_ID:-}"
[[ -n "$surface" && -f "$helper" ]] || return 1
python3 "$helper" --resolve-surface "$surface" --allow-screen 2>/dev/null
}
_codex_cmux_name_current_tab() {
local name="${CODEX_THREAD_NAME:-}"
[[ -n "${name//[[:space:]]/}" ]] || return 0
local cmux_bin="${CMUX_BIN:-/Applications/cmux.app/Contents/Resources/bin/cmux}"
[[ -x "$cmux_bin" ]] || return 0
"$cmux_bin" rename-tab "$name" >/dev/null 2>&1 || true
}
_codex_prompt_builder_fork() {
local fork_from=""
local compact=0
local fork_id
while (( $# )); do
case "$1" in
--fork-from)
[[ $# -ge 2 ]] || { print -u2 -- "missing value for --fork-from"; return 2; }
fork_from="$2"
shift 2
;;
--compact)
compact=1
shift
;;
--)
shift
break
;;
*)
break
;;
esac
done
if (( compact )); then
if [[ -n "$fork_from" && "$fork_from" != "last" ]]; then
fork_id="$(_codex_app_server_fork_compact_latest "$fork_from")" || return 1
else
fork_id="$(_codex_app_server_fork_compact_latest)" || return 1
fi
else
if [[ -n "$fork_from" && "$fork_from" != "last" ]]; then
fork_id="$(_codex_app_server_fork_latest "$fork_from")" || return 1
else
fork_id="$(_codex_app_server_fork_latest)" || return 1
fi
fi
print -r -- "$fork_id"
_codex_cmux_name_current_tab
x resume "$fork_id" "$@"
}
xfl() {
local session_id
local fork_id
session_id="$(_codex_cmux_current_session_id)" && [[ -n "$session_id" ]] && {
fork_id="$(_codex_app_server_fork_latest "$session_id")" || return 1
print -r -- "$fork_id"
_codex_cmux_name_current_tab
x resume "$fork_id" "$@"
return
}
fork_id="$(_codex_app_server_fork_latest)" || return 1
print -r -- "$fork_id"
_codex_cmux_name_current_tab
x resume "$fork_id" "$@"
}
xfc() {
local session_id
local fork_id
session_id="$(_codex_cmux_current_session_id 2>/dev/null)" || session_id=""
if [[ -n "$session_id" ]]; then
fork_id="$(_codex_app_server_fork_compact_latest "$session_id")" || return 1
else
fork_id="$(_codex_app_server_fork_compact_latest)" || return 1
fi
print -r -- "$fork_id"
_codex_cmux_name_current_tab
x resume "$fork_id" "$@"
}
_p_handoff_zsh() {
local fn="${1:?Usage: _p_handoff_zsh <function> [p-args...]}"
shift
p \
--handoff-command zsh \
--handoff-arg -lc \
--handoff-arg "source \"\$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \
--handoff-arg "$fn" \
"$@"
}
p-f() {
local source="${CODEX_FORK_SESSION_ID:-last}"
_p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@"
}
p-c() {
local source="${CODEX_FORK_SESSION_ID:-last}"
_p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@"
}
p-cm() {
_p_handoff_zsh _codex_prompt_builder_fork --fork-from m --compact "$@"
}
zsh/functions/fusion-fix.zsh
# Fusion-first fixer prompt for terse bug reports.
unalias fix 2>/dev/null
fix() {
local bug="$*"
local template_description="Run Fusion on the terse bug, implement the selected fix, and verify it."
local system_prompt="You are an expert fixer. The user will provide an extremely terse bug report, broken behavior, failing command, or vague fix request. Treat that terse input as the full task brief and turn it into a concrete repair plan by inspecting the current repository."
local developer_prompt="You are launched by the zsh fix helper. The user input may be only a few words. First clarify the likely defect from local repo evidence, then use the \$fusion skill before implementing: consult the local Fusion workflow against the bug, wait for terminal Fusion results and read its final artifacts, reconcile the recommendation with source evidence, then implement the fix. Keep changes scoped to the bug, preserve unrelated user work, run focused verification, and report what changed. Do not skip Fusion unless the bug is impossible to evaluate locally or Fusion itself is unavailable; if Fusion is unavailable, state that and continue with source-backed debugging."
if [[ -n "$bug" ]]; then
p \
--instructions "$system_prompt" \
--developer-instructions "$developer_prompt" \
--template-label "Fix" \
--template-description "$template_description" \
"$bug"
else
p \
--instructions "$system_prompt" \
--developer-instructions "$developer_prompt" \
--template-label "Fix" \
--template-description "$template_description"
fi
}
zsh/functions/orchestration-helpers.zsh
# Focused orchestration helper snippets.
muxai() {
local session="${1:-ai}"
local window="${2:-bots}"
local -a cmds=(claude gemini copilot codex)
command -v tmux >/dev/null 2>&1 || {
echo "tmux not found"
return 1
}
local win_id pane_id win_info
if [[ -n "$TMUX" ]]; then
win_info=$(tmux new-window -P -F "#{window_id}|#{pane_id}" -n "$window")
elif tmux has-session -t "$session" 2>/dev/null; then
win_info=$(tmux new-window -t "$session" -P -F "#{window_id}|#{pane_id}" -n "$window")
else
tmux new-session -d -s "$session" -n "$window"
win_info="$(tmux display-message -p -t "$session:$window" "#{window_id}")|$(tmux list-panes -t "$session:$window" -F "#{pane_id}" | head -n1)"
fi
win_id="${win_info%%|*}"
pane_id="${win_info##*|}"
tmux set-window-option -t "$win_id" remain-on-exit on >/dev/null
tmux send-keys -t "$pane_id" "${cmds[1]}" C-m
local current="$pane_id" new_pane i
for (( i=2; i<=${#cmds[@]}; i++ )); do
if (( i % 2 == 0 )); then
new_pane=$(tmux split-window -P -F "#{pane_id}" -t "$current" -h)
else
new_pane=$(tmux split-window -P -F "#{pane_id}" -t "$current" -v)
fi
tmux send-keys -t "$new_pane" "${cmds[i]}" C-m
current="$new_pane"
done
tmux select-layout -t "$win_id" tiled >/dev/null
[[ -z "$TMUX" ]] && tmux attach -t "$session"
}
agent_chain() {
# Lazy-loader shape only. Keep the full pipeline implementation in the local
# zsh source and copy in only the reviewed command surface needed for a demo.
unfunction agent_chain 2>/dev/null || true
for file in \
"$HOME/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh" \
"$HOME/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh"
do
[[ -r "$file" ]] && source "$file"
done
agent_chain "$@"
}
ghost-save() {
unfunction ghost-save 2>/dev/null || true
for file in \
"$HOME/.config/zsh/conf.d/38-git-ghost-checkpoint-dsl.zsh" \
"$HOME/.config/zsh/conf.d/39-git-ghost-maintenance-dsl.zsh"
do
[[ -r "$file" ]] && source "$file"
done
ghost-save "$@"
}
aicm() {
local file="$HOME/.config/zsh/conf.d/43-ai-commit.zsh"
[[ -r "$file" ]] || {
echo "Missing $file" >&2
return 1
}
source "$file"
aicm "$@"
}
zsh/functions/script-kit-process-helpers.zsh
# Process cleanup helpers mentioned in the zsh helper inventory.
pksk() {
local pgids
pgids=("${(@f)$(ps -axo pgid=,command= | awk '
/\/bin\/bash \.\/dev\.sh/ || /cargo-watch watch .*script-kit-gpui/ { print $1 }
' | sort -u)}")
if (( ${#pgids[@]} )); then
local pgid
for pgid in "${pgids[@]}"; do
[[ -n "$pgid" ]] && kill -TERM "-$pgid" 2>/dev/null || true
done
sleep 0.5
for pgid in "${pgids[@]}"; do
[[ -n "$pgid" ]] && kill -KILL "-$pgid" 2>/dev/null || true
done
fi
pkill -9 -f '[s]cript-kit-gpui' 2>/dev/null || true
}
alias ksk='pkill -9 -f "[s]cript-kit-gpui"'
zsh/functions/shell-introspection.zsh
# Zsh function discovery helpers.
funclist() {
setopt localoptions no_xtrace no_verbose
local show_all=false verbose=false pattern=""
while [[ $# -gt 0 ]]; do
case "$1" in
-a|--all) show_all=true; shift ;;
-v|--verbose) verbose=true; shift ;;
*) pattern="$1"; shift ;;
esac
done
local funcs
if $show_all; then
funcs=$(print -l ${(k)functions} | sort)
else
funcs=$(print -l ${(k)functions} | grep -v '^_' | sort)
fi
[[ -n "$pattern" ]] && funcs=$(echo "$funcs" | grep -i "$pattern")
if ! $verbose; then
echo "$funcs"
return
fi
local func file line_num
while IFS= read -r func; do
[[ -z "$func" ]] && continue
file="${functions_source[$func]}"
if [[ -z "$file" || ! -f "$file" ]]; then
printf '\e[1;36m%s\e[0m\n' "$func"
continue
fi
line_num=$(grep -n -m1 -E "^\s*(function\s+)?${func}\s*\(" "$file" 2>/dev/null | cut -d: -f1)
printf '\e[1;36m%s\e[0m\n' "$func"
[[ -n "$line_num" ]] && printf ' %s:%s\n' "$file" "$line_num"
done <<< "$funcs"
}
funcwhere() {
[[ -z "$1" ]] && {
echo "Usage: funcwhere <function_name>"
return 1
}
local func="$1"
[[ $(whence -w "$func" 2>/dev/null) != *function* ]] && {
echo "'$func' is not a function" >&2
return 1
}
local file="${functions_source[$func]}"
[[ -z "$file" || ! -f "$file" ]] && {
echo "Can't find source file for '$func'" >&2
return 1
}
local line
line=$(grep -n -m1 -E "^\s*(function\s+)?${func}\s*\(|eval\s+[\"']${func}\s*\(" "$file" | cut -d: -f1)
[[ -z "$line" ]] && line=1
echo "$file:$line"
}
funced() {
[[ -z "$1" ]] && {
echo "Usage: funced <function_name>"
return 1
}
local func="$1"
[[ $(whence -w "$func" 2>/dev/null) != *function* ]] && {
echo "'$func' is not a function"
return 1
}
local file="${functions_source[$func]}"
[[ -z "$file" || ! -f "$file" ]] && {
echo "Can't find source file for '$func'"
return 1
}
local line
line=$(grep -n -m1 -E "^\s*(function\s+)?${func}\s*\(|eval\s+[\"']${func}\s*\(" "$file" | cut -d: -f1)
[[ -z "$line" ]] && line=1
local editor_cmd="${EDITOR_CMD:-${EDITOR:-vi}}"
local editor_name="${editor_cmd:t}"
case "$editor_name" in
zed) "$editor_cmd" "$file:$line" ;;
cursor|code|code-insiders) "$editor_cmd" -g "$file:$line" ;;
micro|vim|nvim) "$editor_cmd" "+$line" "$file" ;;
*) "$editor_cmd" "$file:$line" ;;
esac
}