1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: Unlicense
  5-->
  6
  7# agentsh
  8
  9[![REUSE status](https://api.reuse.software/badge/git.secluded.site/agentsh)](https://api.reuse.software/info/git.secluded.site/agentsh)
 10[![Fish Shell](https://img.shields.io/badge/fish-3.0%2B-007EC7.svg)](https://fishshell.com/)
 11[![Zsh Shell](https://img.shields.io/badge/zsh-5.4%2B-FFA500.svg)](https://www.zsh.org/)
 12[![scratchanitch.dev badge](https://img.shields.io/badge/scratchanitch-dev-FFC4B5)](https://scratchanitch.dev)
 13[![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](http://unlicense.org/)
 14
 15_Poke [Crush](https://github.com/charmbracelet/crush)—or any other CLI
 16agent—from your shell. Inspired by
 17[zsh-kimi-cli](https://github.com/MoonshotAI/zsh-kimi-cli)_
 18
 19![Shell comment giving instructions for adding the prefix, then the user types 'Say hello', adds the prefix, presses enter, the agent says hello, and the user is dropped to a normal prompt](https://vhs.charm.sh/vhs-2WsmXhqnQK9RktL9NGzz4M.gif)
 20
 21## Features
 22
 23- **Prefix-based activation**: Mark commands with `✨` to send them to your agent
 24- **Quick toggle**: Press `Ctrl-X` to add/remove the prefix from your current
 25  command
 26- **Customizable prefix**: Configure your own prefix character and formatting
 27- **Configurable runner**: Defaults to `crush run --quiet`, but you can point it
 28  at any CLI agent like Claude Code or Kimi CLI or Gemini.
 29
 30## Attribution
 31
 32The Zsh version started as a copy of
 33[zsh-kimi-cli](https://github.com/MoonshotAI/zsh-kimi-cli) by MoonshotAI with
 34`kimi -c "prompt"` swapped out for `crush run --quiet "prompt"`. The Fish plugin
 35was translated and adapted from the Zsh plugin. Both have since diverged.
 36
 37## Requirements
 38
 39- **Zsh**: Version 5.4 or later
 40- **Fish**: Version 3.0 or later
 41- **Runner**: [`crush`](https://github.com/charmbracelet/crush) by default, or
 42  any executable/function referenced by `__AGENTSH_RUNNER`
 43
 44## Installation
 45
 46### Fish
 47
 48#### Manual Installation
 49
 50```fish
 51# Clone the repository
 52git clone https://git.secluded.site/agentsh ~/.config/fish/agentsh
 53
 54# Source the plugin in your config.fish
 55source ~/.config/fish/agentsh/conf.d/agentsh.fish
 56```
 57
 58#### Fundle (recommended)
 59
 60Fundle works directly with git repositories (unlike Fisher), so it can pull from
 61any host:
 62
 63```fish
 64fundle plugin 'agentsh' --url 'https://git.secluded.site/agentsh'
 65fundle install
 66```
 67
 68### Zsh
 69
 70#### Manual (`.zshrc`)
 71
 72```zsh
 73# Clone anywhere you prefer
 74git clone https://git.secluded.site/agentsh ~/.zsh/agentsh
 75
 76# Load the plugin in .zshrc
 77source ~/.zsh/agentsh/agentsh.zsh
 78```
 79
 80#### Oh My Zsh
 81
 82```zsh
 83git clone https://git.secluded.site/agentsh \
 84  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/agentsh
 85
 86# Add to your ~/.zshrc plugins list
 87plugins=(... agentsh)
 88```
 89
 90#### Antigen
 91
 92```zsh
 93antigen bundle https://git.secluded.site/agentsh path:agentsh.zsh
 94antigen apply
 95```
 96
 97#### Zinit
 98
 99```zsh
100zinit light https://git.secluded.site/agentsh
101```
102
103#### Zplug
104
105```zsh
106zplug "https://git.secluded.site/agentsh", use:agentsh.zsh
107```
108
109## Usage
110
111Press `Ctrl-X` to add the prefix before typing your message
112
113```bash
114✨ find all TODO comments in this project
115✨ what is using port 8080?
116```
117
118Type the message, add the prefix, remove the prefix
119
120```bash
121# Type your command first
122show system resource usage
123
124# Press Ctrl-X to add the prefix
125✨ show system resource usage
126
127# Press Ctrl-X again to remove it
128show system resource usage
129```
130
131## Configuration
132
133### Custom Prefix Character
134
135Set these variables before loading the plugin to pick your own prefix.
136
137**Fish:**
138
139```fish
140set -g __AGENTSH_PREFIX_CHAR "🤖"
141set -g __AGENTSH_PREFIX "$__AGENTSH_PREFIX_CHAR "
142```
143
144**Zsh:**
145
146```zsh
147typeset -g __AGENTSH_PREFIX_CHAR
148__AGENTSH_PREFIX_CHAR="🤖"
149__AGENTSH_PREFIX="${__AGENTSH_PREFIX_CHAR} "
150```
151
152### Custom Runner Command
153
154Override the runner to talk to anything other than Crush. The variable is an
155array/list so you can include extra flags—set it before sourcing `agentsh`.
156
157**Fish:**
158
159```fish
160# Example overrides
161set -g __AGENTSH_RUNNER claude -p
162set -g __AGENTSH_RUNNER kimi -c
163```
164
165**Zsh:**
166
167```zsh
168typeset -ga __AGENTSH_RUNNER
169__AGENTSH_RUNNER=(claude -p)
170# or
171__AGENTSH_RUNNER=(kimi -c)
172```
173
174### Prefix Protection
175
176Both Zsh and Fish plugins prevent accidentally deleting the prefix with
177backspace or `Ctrl-W`.
178
179## How It Works
180
181Both plugins work by:
182
1831. **Intercepting command-not-found**: Commands starting with the prefix
184   character trigger the shell's command-not-found handler
1852. **Forwarding to your runner**: The handler strips the prefix and passes the
186   remaining text to the configured runner (defaults to `crush run --quiet`)
1873. **Preserving fallback**: Non-prefixed commands continue to use the shell's
188   normal command-not-found behavior
189
190## Differences from zsh-kimi-cli
191
192While inspired by zsh-kimi-cli, these plugins have several notable differences:
193
194- Defaults to Crush but can target any CLI agent via `__AGENTSH_RUNNER`
195- Support for both Fish and Zsh shells
196- Configurable prefix character and format
197
198## Contributions
199
200Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
201new account to contribute, you don't need to fork this repo, you don't need to
202fiddle with `git send-email`, you don't need to faff with your email client to
203get `git request-pull` working...
204
205You just need:
206
207- Git
208- SSH
209- An SSH key
210
211```sh
212# Clone this repo, make your changes, and commit them
213# Create a new patch request with
214git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
215# After potential feedback, submit a revision to an existing patch request with
216git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
217# List patch requests
218ssh pr.pico.sh pr ls amolith/llm-projects
219```
220
221See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
222complete example workflow.
223
224[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
225[pr.pico.sh]: https://pr.pico.sh
226
227---
228
229Some other tools if this one interested you
230
231- [_nasin pali_](https://git.secluded.site/np) (`np`) - minimal todo/planning CLI for agents
232- [formatted-commit](https://git.secluded.site/formatted-commit) - CLI that turns LLM input into well-formatted Conventional Commits