@@ -0,0 +1,122 @@
+# 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
+
+```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
+
+```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.
@@ -0,0 +1,15 @@
+{
+ "$schema": "https://charm.land/crush.json",
+ "lsp": {
+ "bash": {
+ "command": "bash-language-server",
+ "filetypes": ["zsh"],
+ "root_markers": [".git", "."]
+ },
+ "fish": {
+ "command": "fish-lsp",
+ "args": ["start"],
+ "filetypes": ["fish"]
+ }
+ }
+}