{"id":50782973,"url":"https://github.com/mjtechguy/aishe","last_synced_at":"2026-06-12T05:02:21.055Z","repository":{"id":363958497,"uuid":"1264455039","full_name":"mjtechguy/aishe","owner":"mjtechguy","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-11T03:34:31.000Z","size":685,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"claude/llmsh-natural-language-shell-h3lqvz","last_synced_at":"2026-06-11T05:15:02.485Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mjtechguy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T22:41:48.000Z","updated_at":"2026-06-11T03:34:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mjtechguy/aishe","commit_stats":null,"previous_names":["mjtechguy/aishe"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mjtechguy/aishe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjtechguy%2Faishe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjtechguy%2Faishe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjtechguy%2Faishe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjtechguy%2Faishe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mjtechguy","download_url":"https://codeload.github.com/mjtechguy/aishe/tar.gz/refs/heads/claude/llmsh-natural-language-shell-h3lqvz","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjtechguy%2Faishe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34229624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T05:02:18.062Z","updated_at":"2026-06-12T05:02:21.044Z","avatar_url":"https://github.com/mjtechguy.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aishe\n\nA natural-language-aware shell. `aishe` behaves like zsh for real commands, and\ntreats anything that is not a command as a natural-language request handled by an\nLLM. The model either **suggests** a command for you to confirm, or **runs\nautonomously** in a tool-use loop.\n\n```\n~/projects/app ❯ git status            # runs exactly like zsh\n~/projects/app ❯ whats eating my disk  # LLM suggests: du -sh * | sort -rh | head\n```\n\naishe does not reimplement a shell grammar. It owns the prompt and input loop and\ndelegates execution of shell lines to `zsh -c` (falling back to `bash -c`), so\npipes, globs, redirection, subshells, and interactive programs (vim, ssh, top)\nall work unmodified.\n\n## Contents\n\n- [Install](#install)\n- [Quickstart](#quickstart)\n- [Modes](#modes)\n- [Front-ends](#front-ends)\n- [Providers](#providers)\n- [Meta commands and slash-commands](#meta-commands-and-slash-commands)\n- [Custom commands and skills](#custom-commands-and-skills)\n- [Token usage and cost](#token-usage-and-cost)\n- [Safety gate](#safety-gate)\n- [Prompt and theming](#prompt-and-theming)\n- [Startup file (.aishrc)](#startup-file-aishrc)\n- [Configuration](#configuration)\n- [Documentation](#documentation)\n- [Development](#development)\n\n## Install\n\nRequires Rust 1.80 or newer and `zsh` or `bash` on your `PATH`. Targets macOS\n(arm64 / x86_64) and Linux (x86_64 / arm64).\n\nInstall a prebuilt binary from a tagged release, or build from source:\n\n```sh\ncargo binstall aishe              # prebuilt binary, no Rust build (cargo-binstall)\n# or build from a checkout:\ncargo install --path .            # installs to ~/.cargo/bin\ncargo build --release             # or just the binary at target/release/aishe\n```\n\nReleases also attach per-platform tarballs (`aishe-\u003ctarget\u003e.tar.gz` + `.sha256`),\nand there is a Homebrew formula template in [`packaging/`](packaging/aishe.rb).\nSee [docs/installation.md](docs/installation.md) for all options and shell\ncompletions (`aishe completions \u003cshell\u003e`).\n\nSee [docs/installation.md](docs/installation.md) for the full guide, including\nuninstalling and the planned prebuilt packages.\n\n## Quickstart\n\n1. Set your API key in the environment. It is never written to the config file.\n\n   ```sh\n   export ANTHROPIC_API_KEY=sk-ant-...      # or OPENAI_API_KEY=...\n   ```\n\n2. Start aishe. On first run an interactive wizard writes\n   `~/.config/aishe/config.toml` (provider, API key env var, model, default mode).\n\n   ```sh\n   aishe\n   ```\n\n3. Type real commands as usual, or type a request in plain English.\n\nNot sure your setup is right? Run `aishe doctor` for a quick check of your shell,\nconfig, resolved front-end, provider, and API key.\n\nA full walkthrough is in [docs/getting-started.md](docs/getting-started.md).\n\n## Modes\n\n| Mode      | Glyph | Behavior                                                                    |\n|-----------|:-----:|-----------------------------------------------------------------------------|\n| `suggest` |  `❯`  | Default. The LLM proposes a command; you confirm with `[Enter] / [e]dit / [n]`. |\n| `auto`    |  `»`  | Commands the safety gate deems safe run immediately; dangerous ones still require typing `yes`. |\n| `yolo`    |  `⚡`  | Agentic loop: the model runs commands, reads output, and iterates until done. |\n\nIn yolo, beyond running commands the model can call built-in tools to edit files\nprecisely (`read_file`/`write_file`/`edit_file`/`list_dir`, `file_tools`) and read\nthe web (`fetch_url`, `web_tool`) instead of fighting `sed`/heredocs/`curl`; both\nare on by default. Configure [MCP servers](docs/mcp.md) under `[mcp_servers]` and\ntheir tools join the loop too (`aishe mcp` lists them).\n\nSwitch at any time with `aishe mode auto`, or start with `aishe --mode yolo`. See\n[docs/modes.md](docs/modes.md) for streaming, structured output, and input\nprefixes.\n\n### Input prefixes\n\n- `?\u003ctext\u003e` forces natural-language, for example `?how do I find large files`\n- `!\u003ccmd\u003e` forces shell and bypasses the safety gate, for example `!rm -rf build`\n\nAfter a command fails, type `?` on the next line to ask the LLM to diagnose the\nerror.\n\n## Front-ends\n\nThere are three ways to use aishe, in increasing order of real-zsh fidelity.\nDetails in [docs/front-ends.md](docs/front-ends.md).\n\n1. **zsh-PTY (default when zsh is present).** aishe runs your real interactive\n   zsh inside a pseudo-terminal, so your full `~/.zshrc` and every plugin you\n   already use (zsh-autosuggestions, zsh-syntax-highlighting, fzf-tab,\n   powerlevel10k, oh-my-zsh, completions) work unmodified. A\n   `command_not_found_handler` routes natural language to the LLM.\n\n   ```sh\n   aishe              # \"auto\" front-end uses zsh-PTY when zsh is on $PATH\n   aishe zsh          # force it (same as aishe --pty, or front_end = \"zsh-pty\")\n   aishe --no-pty     # force the built-in reedline editor instead\n   ```\n\n2. **Built-in reedline editor.** A self-contained line editor with\n   context-aware tab completion, history autosuggestions, `Ctrl-R` history\n   search, history expansion, multi-line continuation, syntax highlighting,\n   emacs or vi keymaps, and optional\n   [inline AI ghost text](docs/ghost-text.md) (`aishe ghost on`). It also brings\n   a lot of zsh ergonomics: a rich prompt (command duration and git\n   staged/dirty/ahead-behind/stash markers), navigation (autocd, directory stack,\n   `AUTO_PUSHD`, `cdpath`, named dirs `~proj`), history filtering\n   (`HIST_IGNORE_DUPS`, `HISTIGNORE`), and spelling correction (`CORRECT`). See\n   [docs/front-ends.md](docs/front-ends.md).\n\n3. **Native zsh/bash hook.** Add `eval \"$(aishe init zsh)\"` to your `~/.zshrc`\n   (or `~/.bashrc` with `init bash`) to keep your own shell and editor while\n   routing unknown input to aishe. See\n   [docs/shell-integration.md](docs/shell-integration.md).\n\n## Providers\n\naishe talks to two provider shapes: the **Anthropic Messages API** and any\n**OpenAI-compatible Chat Completions API**. The OpenAI shape covers OpenAI,\nGroq, Ollama, OpenRouter, Together, and similar services through `base_url`.\n\n```toml\n[providers.openai]\nbase_url = \"https://api.groq.com/openai\"   # or http://localhost:11434 for Ollama\napi_key_env = \"GROQ_API_KEY\"\nmodel = \"openai/gpt-oss-120b\"\n```\n\nAPI keys are read only from the named environment variable, never stored in the\nconfig. See [docs/providers.md](docs/providers.md) for per-provider setup.\n\n## Meta commands and slash-commands\n\n```\naishe mode [suggest|auto|yolo]    show or set the interaction mode\naishe model [NAME]                show or set the model\naishe provider [anthropic|openai] show or set the provider\naishe editor [emacs|vi]           show or set the line-editor keymap\naishe frontend [auto|reedline|zsh-pty]  show or set the front-end\naishe stream [on|off]             show or toggle token streaming\naishe structured [schema|json|prompt]   output-format strategy (default: schema)\naishe theme [PRESET]              show or set the color preset\naishe usage                       session token and cost usage\naishe reset                       clear conversation memory\naishe ghost [on|off]              inline AI ghost-text autosuggestion\naishe commands                    list custom slash-commands\naishe skills                      list model-invoked skills\naishe config                      print the active config\naishe rehash                      rebuild the command cache\naishe help                        show help\n```\n\nEach meta command also works as a slash-command (Claude Code style), for example\n`/mode auto`, `/config`, `/help`. They are tab-completable, and `/`-prefixed\npaths like `/usr/bin/x` still run normally. Full reference in\n[docs/commands.md](docs/commands.md).\n\n## Conversation memory\n\nIn the interactive REPL, aishe remembers recent natural-language turns so\nfollow-ups have context: after \"create alpha.txt containing apple\", a follow-up\n\"now do the same for beta.txt\" knows what \"the same\" means. Memory lives only for\nthe session (never written to disk), is capped in size, and is cleared with\n`aishe reset`. Turn it off with `memory = false`. See [docs/modes.md](docs/modes.md).\n\n## Custom commands and skills\n\nDrop Markdown files into `~/.config/aishe/commands/` (user) or\n`\u003cproject\u003e/.aishe/commands/` (project, overrides user) to add your own\n`/commands`. The file name is the command (`bigfiles.md` becomes `/bigfiles`).\n\n```md\n---\ndescription: Suggest a command to find the biggest files\nmode: suggest            # suggest | auto | yolo (NL commands); default = current mode\n# shell: true            # run the body as a shell command instead of an NL request\n---\nShow the 10 largest files under $ARGUMENTS, human-readable, largest first.\n```\n\n**Skills** are the model-invoked counterpart. Put skill files in\n`~/.config/aishe/skills/` as `\u003cname\u003e/SKILL.md`. In yolo mode aishe advertises\neach skill's `name` and `description`; when your request matches, the model pulls\nthe skill's full instructions into context on demand.\n\nThe formats match Claude Code, so real Agent Skills from\n[anthropics/skills](https://github.com/anthropics/skills) and slash commands from\ncollections like [wshobson/commands](https://github.com/wshobson/commands) drop\nin unchanged. Ready-made examples live in [examples/commands/](examples/commands/)\nand [examples/skills/](examples/skills/). Full guide:\n[docs/custom-commands-and-skills.md](docs/custom-commands-and-skills.md).\n\n## Token usage and cost\n\naishe meters every model call. After each interaction it prints a dim\n`N in / N out / N req / ~$cost` line (disable with `show_usage = false`), and\n`aishe usage` shows the session total. Costs come from a built-in price table\n(USD per 1M tokens) that you can override per model in `[pricing]`. Set\n`budget_usd` to stop calling the model once the estimated session cost reaches a\nlimit.\n\n```toml\n[aishe]\nbudget_usd = 0.50          # stop past ~$0.50 per session (0 = unlimited)\n\n[pricing.\"openai/gpt-oss-120b\"]\ninput = 0.15\noutput = 0.60\n```\n\nMore in [docs/usage-and-cost.md](docs/usage-and-cost.md).\n\n## Safety gate\n\nBefore running an LLM-proposed command (in suggest and auto, and for yolo tool\ncalls when `yolo_confirm_dangerous = true`), aishe screens for irreversible\noperations: `rm -rf`, `dd of=/dev/...`, `mkfs`, fork bombs, `curl ... | sh`,\n`git push --force` to main, `shutdown` and `reboot`, and more. Dangerous commands\nprint a red panel and require you to type the full word `yes`.\n\nThe gate is path-aware for `rm -rf`: an in-tree relative path like\n`rm -rf node_modules` runs without fuss, while absolute, home, variable, glob, or\nescaping targets are flagged. The gate does not apply to commands you type\nyourself or to `!`-forced lines. Details in [docs/safety.md](docs/safety.md).\n\n## Logging and privacy\n\naishe sends an environment context block (including your recent commands) with\neach request. To avoid leaking credentials, it **redacts likely secrets**\n(tokens, passwords, URL credentials) from that block before sending. This is on\nby default (`redact_secrets`).\n\nAn optional **audit log** records every AI call, response (with token usage), and\nAI-initiated command (with exit code) as JSONL. It is off by default; enable it\nwith `[logging] enabled = true` or `AISHE_LOG=1`. Logged text is redacted too.\nSee [docs/logging.md](docs/logging.md).\n\n## Prompt and theming\n\nThe reedline front-end supports a custom left prompt (`prompt_format` with\n`{cwd}`, `{mode}`, `{model}`, `{exit}`), a right prompt with `model and mode` and\na git branch segment, and color themes. Pick a preset (`default`, `vivid`,\n`mono`, `nord`, `gruvbox`) or override individual roles.\n\n```toml\n[theme]\npreset = \"nord\"\ncwd = \"bright-cyan\"\n```\n\nSee [docs/prompt-and-theming.md](docs/prompt-and-theming.md).\n\n## Startup file (.aishrc)\n\naishe sources `~/.aishrc` and `~/.config/aishe/aishrc` (in that order) into every\ndelegated command, so aliases, functions, and exports you define there are\navailable everywhere and recognized at the prompt.\n\n```sh\n# ~/.aishrc\nalias gs='git status'\nalias ll='ls -lah'\nexport EDITOR=nvim\ngco() { git checkout \"$@\"; }\n```\n\nA ready-to-copy example is at [examples/aishrc](examples/aishrc).\n\n## Configuration\n\nThe config file lives at `~/.config/aishe/config.toml`. A fully annotated example\nis at [examples/config.toml](examples/config.toml), and every field is documented\nin [docs/configuration.md](docs/configuration.md).\n\n```toml\n[aishe]\nmode = \"suggest\"               # suggest | auto | yolo\nprovider = \"anthropic\"         # anthropic | openai\nfront_end = \"auto\"             # auto | reedline | zsh-pty\nedit_mode = \"emacs\"            # emacs | vi\nstructured = \"schema\"          # schema | json | prompt\nstream = false                 # stream answers token-by-token\nshow_usage = true              # print token/cost after each model call\nbudget_usd = 0.0               # 0 = unlimited\nmemory = true                  # remember recent turns (aishe reset to clear)\nghost_text = false             # inline AI ghost text (aishe ghost on)\nredact_secrets = true          # scrub secrets from the model context\nreport_time = 3                # show command duration over N seconds\nauto_pushd = false             # zsh AUTO_PUSHD\ncorrect = false                # zsh CORRECT (fix mistyped commands)\n# many more fields: see examples/config.toml and docs/configuration.md\n\n[providers.anthropic]\nbase_url = \"https://api.anthropic.com\"\napi_key_env = \"ANTHROPIC_API_KEY\"\nmodel = \"claude-sonnet-4-20250514\"\n\n[providers.openai]\nbase_url = \"https://api.openai.com\"\napi_key_env = \"OPENAI_API_KEY\"\nmodel = \"gpt-4o\"\n```\n\n## Documentation\n\nThe [docs/](docs/) directory has the full user guide:\n\n- [Installation](docs/installation.md)\n- [Getting started](docs/getting-started.md)\n- [Modes](docs/modes.md)\n- [Front-ends](docs/front-ends.md)\n- [Inline AI ghost text](docs/ghost-text.md)\n- [Providers](docs/providers.md)\n- [Configuration reference](docs/configuration.md)\n- [Commands and slash-commands](docs/commands.md)\n- [Custom commands and skills](docs/custom-commands-and-skills.md)\n- [Token usage and cost](docs/usage-and-cost.md)\n- [Safety gate](docs/safety.md)\n- [Logging and privacy](docs/logging.md)\n- [Prompt and theming](docs/prompt-and-theming.md)\n- [Shell integration and .aishrc](docs/shell-integration.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Roadmap](docs/ROADMAP.md)\n\n## Development\n\n```sh\ncargo build\ncargo test            # unit and integration (integration tests spawn a real shell)\ncargo clippy --all-targets -- -D warnings\ncargo fmt --check\n\n# end-to-end validation harness (no API key needed for the deterministic suites)\ncargo build --release \u0026\u0026 python3 tests/admin_validation.py\n```\n\nSee [docs/development.md](docs/development.md) for the test layout and how the\nvalidation harness works.\n\n## License\n\nSee [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjtechguy%2Faishe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmjtechguy%2Faishe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjtechguy%2Faishe/lists"}