shell-handoff

shell-handoff

Make a skill or wrapper invokable from the user's shell as a command, without writing to PATH directories. The sandbox blocks writes to ~/bin/, /usr/local/bin/, etc. by design — that boundary exists so the agent never silently defines what happens when the user types a command. Hand off through an explicit aliases file the user sources from their shell config.

When to use

• Wrapping lazar (renderer, formatter, custom invocation flags).
• Authoring any skill that "should be a shell command" (e.g. glazar, lt, note).
• Anytime you'd otherwise reach for cp foo ~/bin/ or cp foo /usr/local/bin/ and hit Operation not permitted.

How to use

The aliases file lives at:

$LAZAR_HOME/workspace/aliases.sh

Workspace is in the writable allowlist. --reset-all wipes workspace, so aliases vanish predictably — the agent's user-facing surface always matches its current state.

Recipe

1. Ensure the aliases file exists with a header:

   mkdir -p $LAZAR_HOME/workspace
   if [ ! -f $LAZAR_HOME/workspace/aliases.sh ]; then
     cat > $LAZAR_HOME/workspace/aliases.sh <<'EOF'
   # lazar shell aliases — generated by skills.
   # Source from .zshrc:
   #   [ -f $LAZAR_HOME/workspace/aliases.sh ] && source $LAZAR_HOME/workspace/aliases.sh
   EOF
   fi
   

2. Append your alias or function (always include a marker comment so duplicates can be detected and removed later):

   # simple alias
   cat >> $LAZAR_HOME/workspace/aliases.sh <<'EOF'
   
   # alias: <name> (skill: <skill-name>)
   alias <name>='<command>'
   EOF
   
   # function form (when args matter)
   cat >> $LAZAR_HOME/workspace/aliases.sh <<'EOF'
   
   # function: <name> (skill: <skill-name>)
   <name>() {
     lazar -p "$*" 2>/dev/null | glow -
   }
   EOF
   

3. Tell the user what just happened. If aliases.sh didn't exist before, this is their first-time setup:

   Add this one line to ~/.zshrc (or ~/.bashrc):
       [ -f $LAZAR_HOME/workspace/aliases.sh ] && source $LAZAR_HOME/workspace/aliases.sh
   Then: source ~/.zshrc