AGENTS.md

AGENTS

This repository provides a small, dependency-free shell plugin that routes prefixed commands from the interactive shell to a configured CLI agent (defaults to Crush). It supports Zsh and Fish.

Repository layout

  • agentsh.zsh — Zsh plugin (command-not-found handler, ZLE widgets, keybindings)
  • conf.d/agentsh.fish — Fish plugin (command-not-found handler, keybindings)
  • README.md — User-facing installation, configuration, and usage
  • LICENSES/Unlicense.txt — License

No build system, package manifest, or tests are present.

Core behavior and data flow

  1. User types a command optionally prefixed with a special character (default "✨").
  2. The shell cannot resolve the command and invokes the command-not-found handler.
  3. Plugin checks for prefix:
    • Prefix as separate token: prefix-only + rest of words
    • Prefix attached to first token: "✨ask …"
  4. If prefixed, remaining words are joined with spaces into a single prompt string and passed as one argument to the configured runner command.
  5. If not prefixed (or runner missing), control falls back to any previously-defined handler or emits a standard not-found message.

References:

  • Zsh handler: agentsh.zsh:31-101 (joins with ${(j: :)...} and executes ${__AGENTSH_RUNNER[@]} with the prompt as a single argument)
  • Fish handler: conf.d/agentsh.fish:27-92 (joins with string join ' ')
  • Previous handler preservation: agentsh.zsh:26-29, conf.d/agentsh.fish:22-25

Note: Because tokens are re-joined with spaces, original quoting is not preserved (suitable for natural language prompts).

Keybindings and input protection

  • Toggle prefix with Ctrl-X
    • Zsh binds in "emacs" and "viins" keymaps: agentsh.zsh:214-223
    • Fish binds \cx: conf.d/agentsh.fish:165-169
  • Prevent deleting the prefix when active
    • Zsh wraps backward delete/kill widgets and vi variants: agentsh.zsh:239-243
    • Fish binds guards for backspace, Alt+Backspace, Ctrl+W (insert and default maps): conf.d/agentsh.fish:170-189
  • Prefix persistence across prompts
    • Zsh: inserts prefix on new line when active: agentsh.zsh:124-137
    • Fish: repaints on postexec when active: conf.d/agentsh.fish:120-125

Configuration (set before sourcing)

Defaults are provided if unset.

  • Prefix character and text
    • Zsh defaults: agentsh.zsh:8-13
    • Fish defaults: conf.d/agentsh.fish:8-14
  • Runner command (array/list)
    • Zsh default: ("crush" "run" "--quiet") — agentsh.zsh:14-17
    • Fish default: crush run --quiet — conf.d/agentsh.fish:16-18

Examples (from README.md):

Fish

set -g __AGENTSH_PREFIX_CHAR "🤖"
set -g __AGENTSH_PREFIX "$__AGENTSH_PREFIX_CHAR "
# Example overrides
set -g __AGENTSH_RUNNER claude -p
set -g __AGENTSH_RUNNER kimi -c

Zsh

typeset -g __AGENTSH_PREFIX_CHAR
__AGENTSH_PREFIX_CHAR="🤖"
__AGENTSH_PREFIX="${__AGENTSH_PREFIX_CHAR} "

typeset -ga __AGENTSH_RUNNER
__AGENTSH_RUNNER=(claude -p)
# or
__AGENTSH_RUNNER=(kimi -c)

Development and manual verification

  • No build system present; this plugin is sourced at runtime.
  • Load locally for testing (use paths per README installation):
    • Fish: source ~/.config/fish/agentsh/conf.d/agentsh.fish
    • Zsh: source ~/.zsh/agentsh/agentsh.zsh
  • Smoke test: toggle with Ctrl-X, type a prefixed prompt; ensure the runner binary in __AGENTSH_RUNNER[1] (Zsh) / first word (Fish) exists on PATH.

Linting and static analysis

Fish shell (conf.d/agentsh.fish)

fish_indent — Built-in Fish formatter and syntax checker

  • Check syntax: fish_indent conf.d/agentsh.fish >/dev/null
  • Format in-place: fish_indent -w conf.d/agentsh.fish
  • Installed with Fish shell, no separate installation needed

Zsh shell (agentsh.zsh)

shellcheck — Static analysis for shell scripts

  • Check for issues: shellcheck agentsh.zsh
  • Install: brew install shellcheck or sudo apt-get install shellcheck
  • May flag some Zsh-specific idioms as non-POSIX; review warnings contextually

shfmt — Shell script formatter

  • Check formatting: shfmt -d agentsh.zsh
  • Format in-place: shfmt -w agentsh.zsh
  • Install: go install mvdan.cc/sh/v3/cmd/shfmt@latest or brew install shfmt

Naming and style patterns

  • Public configuration variables are uppercased with __AGENTSH_*.
  • Internal functions and symbols use __agentsh_* prefix.
  • Zsh functions use emulate -L zsh for local, safe options: agentsh.zsh:32,104,125,141,163,171,189,201.

Gotchas and interoperability

  • Only the prompt string (space-joined) is passed to the runner as a single argument.
  • Zsh binds only "emacs" and "viins" keymaps by default; other keymaps are not bound in this repo.
  • If runner is missing, plugin delegates to any previously-defined not-found handler when possible; otherwise prints an error and returns 127.

Contributing

See README.md:198-221 for patch-request workflow using pr.pico.sh.