Home

Ash

When you install ash on your Linux or MacOS machine you are upgrading the Bash, ZSH, Fish, or bash-compatible shell with access to an AI. This allows you to interact with an AI or automate tasks from the command line without having to change applications. It means that the AI is available to you on a remote machine over ssh. It means you can incorporate agent work into your shell scripts. This works surprisingly well on very small machines because the majority of the work happens in the cloud.

Requirements

• An AI that supports Open AI's API, which almost all cloud providers do. You can also use local AI through tools like llamacpp-server, Ollama, etc.
• An OS that runs the bash, zsh (MacOS default), or Fish shell.
• The Authentication key for your account on the paid AI providers

You don't need a big fancy and expensive AI for Ash. The Gemma4-31B model is perfectly capable of running the tools, and reasoning through system administration tasks. This model is available on the free tier of Ollama Cloud and potentially other providers. I started a discussion to help you find a suitable and inexpensive model: Inexpensive AI for Ash

Features

• Intermix unix command line calls (ls, cat, top) with AI prompts ("Which process is using the most IO right now?")
• Use local or cloud provider AI endpoints over HTTPS
• Shares and reuses connections via the Connection-Sharing broker
• Auto-detects provider adapters (ollama, openai, google, anthropic, cohere, bedrock) from endpoint for zero touch install if you want to use your existing paid subscription
• During install the list of available models is pulled from your provider for each configuration
• Uses provider-native tool calling through per-provider adapters
• Can attach files (images or documents) to a request with --attach <path> (repeatable); currently sent to OpenAI-compatible providers
• Optional streaming responses from providers that support it via ASH_STREAM (currently OpenAI only)
• Can execute allowlisted Unix commands and conditionally available Python as AI tools — see Conditional-Python-Execution
• Provisions an isolated Python-Environment for bundled Python tools, separate from your system Python
• Uses your python scripts in ~/.ash/tools as AI tools — see Guide-to-Creating-Python-Tools
• Uses native multi-language plugins in ~/.ash/plugins (Go, Rust, TypeScript) — see Plugin-Security-and-Architecture, Plugin-What-Time-Is-It, Plugin-Flip-A-Coin, Plugin-Calculator
• Detailed guides for authoring native plugins: Authoring-Plugins-in-Go, Authoring-Plugins-in-Rust, Authoring-Plugins-in-TypeScript
• Complete developer setup instructions across all OS package managers: Developer-Environment-Setup
• Uses the internal $TOOLS_DIR_LIST and $PLUGINS_DIR_LIST prompt substitutions to describe permitted managed scripts and native plugins
• Composes into shell scripts and Makefiles like any other CLI — see Incorporating-Ash-into-Shell-Scripts
• Security model, access control (.ash_allow / .ash_deny), threat model, and environment variables documented in Security-Model-and-Environment-Variables
• Can schedule one-off and recurring prompt invocations via at and crontab — see Scheduled-and-Recurring-Jobs
• Maintains recurring-job inventory and management through AI tools
• Enables provider-native caching by default when supported
• Shows an ANSI-friendly thinking indicator while waiting for the AI response
• Supports Ctrl-C to abort an in-flight request
• Keeps recent chat history across calls so you can continue to conversation or revise previous requests
• Uses ~/.ash/.ash_system as the canonical system prompt which you can customize
• Supports emoji input/output (UTF-8)
• Renders markdown output to terminal styling with ANSI fallback safety
• Provides a session-scoped scratch workspace under ~/.ash/scratch/<session-id>/ for temporary notes, plans, and helper files
• Automatically cleans stale scratch directories older than 48 hours with no access in the last 24 hours
• Structured debug logging and an execution dashboard via ASH_VERBOSE — see Debugging-with-ASH_VERBOSE

Installation

1. Go to VersionX.ai
2. Click Install in the top left corner of the page
3. Copy the one-line install command (source code)
4. Verify you have curl installed (sudo apt install curl)
5. Execute the script
6. Exit your shell or reload it, because the installer has modified your .bashrc file.
7. Prompt the AI: "What time is it?"

Updating ash

1. ash update (source)

This will verify the latest release is newer than the current running version. Download the latest release. Check its signature. Then install it. During the install it will ask to replace any of your configuration files that you have modified. The default is to not replace them.

You will not need to reload your shell after the update.

Uninstalling ash

1. rm -Rf ~/.ash will remove the tools, scratch files, history, and configuration
2. rm ~/.local/bin/ash will remove the ash executable
3. Edit your .bashrc (or .zshrc) to remove the lines in the following section:

# >>> ash install >>>
[ -f "$HOME/.ash/.ash_env" ] && . "$HOME/.ash/.ash_env"
[ -f "$HOME/.ash/.ash_bashrc" ] && . "$HOME/.ash/.ash_bashrc"
# <<< ash install <<<

4. Exit all shells sessions, this shuts down any running Connection-Sharing brokers.