From 2b1291adef533cc6362f72b0e43ca8dc8027e778 Mon Sep 17 00:00:00 2001 From: Amolith Date: Sun, 9 Nov 2025 16:22:42 -0700 Subject: [PATCH] docs: add AGENTS.md and Crush config Assisted-by: Claude Sonnet 4.5 via Crush --- AGENTS.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++ crush.json | 15 +++++++ 2 files changed, 137 insertions(+) create mode 100644 AGENTS.md create mode 100644 crush.json diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000000000000000000000000000000000..ed693b8b6c7f7c3390b1962fe742f23a6e9b4845 --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/crush.json b/crush.json new file mode 100644 index 0000000000000000000000000000000000000000..c80aa6e5332512450b49dcc16d408b4cf08d2af6 --- /dev/null +++ b/crush.json @@ -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"] + } + } +}