1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: Unlicense
  5-->
  6
  7# AGENTS
  8
  9This 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.
 10
 11## Repository layout
 12
 13- agentsh.zsh — Zsh plugin (command-not-found handler, ZLE widgets, keybindings)
 14- conf.d/agentsh.fish — Fish plugin (command-not-found handler, keybindings)
 15- README.md — User-facing installation, configuration, and usage
 16- LICENSES/Unlicense.txt — License
 17
 18No build system, package manifest, or tests are present.
 19
 20## Core behavior and data flow
 21
 221. User types a command optionally prefixed with a special character (default "✨").
 232. The shell cannot resolve the command and invokes the command-not-found handler.
 243. Plugin checks for prefix:
 25   - Prefix as separate token: prefix-only + rest of words
 26   - Prefix attached to first token: "✨ask …"
 274. If prefixed, remaining words are joined with spaces into a single prompt string and passed as one argument to the configured runner command.
 285. If not prefixed (or runner missing), control falls back to any previously-defined handler or emits a standard not-found message.
 29
 30References:
 31- Zsh handler: agentsh.zsh:31-101 (joins with ${(j: :)...} and executes `${__AGENTSH_RUNNER[@]}` with the prompt as a single argument)
 32- Fish handler: conf.d/agentsh.fish:27-92 (joins with `string join ' '`) 
 33- Previous handler preservation: agentsh.zsh:26-29, conf.d/agentsh.fish:22-25
 34
 35Note: Because tokens are re-joined with spaces, original quoting is not preserved (suitable for natural language prompts).
 36
 37## Keybindings and input protection
 38
 39- Toggle prefix with Ctrl-X
 40  - Zsh binds in "emacs" and "viins" keymaps: agentsh.zsh:214-223
 41  - Fish binds `\cx`: conf.d/agentsh.fish:165-169
 42- Prevent deleting the prefix when active
 43  - Zsh wraps backward delete/kill widgets and vi variants: agentsh.zsh:239-243
 44  - Fish binds guards for backspace, Alt+Backspace, Ctrl+W (insert and default maps): conf.d/agentsh.fish:170-189
 45- Prefix persistence across prompts
 46  - Zsh: inserts prefix on new line when active: agentsh.zsh:124-137
 47  - Fish: repaints on postexec when active: conf.d/agentsh.fish:120-125
 48
 49## Configuration (set before sourcing)
 50
 51Defaults are provided if unset.
 52
 53- Prefix character and text
 54  - Zsh defaults: agentsh.zsh:8-13
 55  - Fish defaults: conf.d/agentsh.fish:8-14
 56- Runner command (array/list)
 57  - Zsh default: `("crush" "run" "--quiet")` — agentsh.zsh:14-17
 58  - Fish default: `crush run --quiet` — conf.d/agentsh.fish:16-18
 59
 60Examples (from README.md):
 61
 62Fish
 63
 64```fish
 65set -g __AGENTSH_PREFIX_CHAR "🤖"
 66set -g __AGENTSH_PREFIX "$__AGENTSH_PREFIX_CHAR "
 67# Example overrides
 68set -g __AGENTSH_RUNNER claude -p
 69set -g __AGENTSH_RUNNER kimi -c
 70```
 71
 72Zsh
 73
 74```zsh
 75typeset -g __AGENTSH_PREFIX_CHAR
 76__AGENTSH_PREFIX_CHAR="🤖"
 77__AGENTSH_PREFIX="${__AGENTSH_PREFIX_CHAR} "
 78
 79typeset -ga __AGENTSH_RUNNER
 80__AGENTSH_RUNNER=(claude -p)
 81# or
 82__AGENTSH_RUNNER=(kimi -c)
 83```
 84
 85## Development and manual verification
 86
 87- No build system present; this plugin is sourced at runtime.
 88- Load locally for testing (use paths per README installation):
 89  - Fish: `source ~/.config/fish/agentsh/conf.d/agentsh.fish`
 90  - Zsh: `source ~/.zsh/agentsh/agentsh.zsh`
 91- 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.
 92
 93## Linting and static analysis
 94
 95### Fish shell (conf.d/agentsh.fish)
 96
 97**fish_indent** — Built-in Fish formatter and syntax checker
 98- Check syntax: `fish_indent conf.d/agentsh.fish >/dev/null`
 99- Format in-place: `fish_indent -w conf.d/agentsh.fish`
100- Installed with Fish shell, no separate installation needed
101
102### Zsh shell (agentsh.zsh)
103
104**shellcheck** — Static analysis for shell scripts
105- Check for issues: `shellcheck agentsh.zsh`
106- Install: `brew install shellcheck` or `sudo apt-get install shellcheck`
107- May flag some Zsh-specific idioms as non-POSIX; review warnings contextually
108
109**shfmt** — Shell script formatter
110- Check formatting: `shfmt -d agentsh.zsh`
111- Format in-place: `shfmt -w agentsh.zsh`
112- Install: `go install mvdan.cc/sh/v3/cmd/shfmt@latest` or `brew install shfmt`
113
114## Naming and style patterns
115
116- Public configuration variables are uppercased with `__AGENTSH_*`.
117- Internal functions and symbols use `__agentsh_*` prefix.
118- Zsh functions use `emulate -L zsh` for local, safe options: agentsh.zsh:32,104,125,141,163,171,189,201.
119
120## Gotchas and interoperability
121
122- Only the prompt string (space-joined) is passed to the runner as a single argument.
123- Zsh binds only "emacs" and "viins" keymaps by default; other keymaps are not bound in this repo.
124- If runner is missing, plugin delegates to any previously-defined not-found handler when possible; otherwise prints an error and returns 127.
125
126## Contributing
127
128See README.md:198-221 for patch-request workflow using pr.pico.sh.