Documentation

Get productive with aish.

aish is an AI-native shell — no POSIX layer underneath, just a stateful agent loop. Describe what you want; aish understands, calls the right tools over MCP, reads and writes files, and runs your programs. This is a first-pass guide to installing, the core concepts, and the command surface.

Install

aish is written in Rust and builds from source. Clone the repo, build a release binary, and open the REPL.

$ git clone https://github.com/LightHeart-Ventures/aish
$ cd aish && cargo build --release
$ ./target/release/aish

Already running aish? Pull the latest release in place with :update.

Your first command

Running aish opens the interactive REPL. Type intent in plain language — aish parses it, picks tools, and streams the work back.

> list the top 10 files by size in /home
→ scanning /home · sorting by size · top 10
✓ done — 10 files, largest 2.4 GB (backup.tar.zst)

There's no syntax to memorize. You state the goal; aish translates it into concrete tool calls and shows you what it did.

Requirements

A recent Rust toolchain (1.70+) to build from source.
Linux or macOS. On macOS, if the binary is killed on launch, see Troubleshooting.
An ANTHROPIC_API_KEY for the cloud backend — or nothing at all to run fully offline with a local model.

How aish works

Traditional shells parse a command string and exec a process. aish replaces that with a stateful agent loop:

Intent in — you describe a goal in natural language.
Reason & plan — aish decides which tools to call, in what order.
Act — it forks/execs real programs, reads/writes files, and calls MCP tools.
Observe & iterate — it reads the results, corrects course, and continues until the goal is met.
Results out — you get the outcome, streamed, with the reasoning visible.

Because the loop is stateful, aish carries context across steps instead of forgetting between commands — the thread of what you were trying to do never drops on the floor.

Sessions & state

A session holds your working directory, environment, and background jobs. aish remembers what just happened, so follow-up intents build on prior steps.

Working directory — natural-language "cd" updates session state for everything after.
Jobs — long-running work runs in the background; manage it with :jobs and :kill.
Memory — durable facts (projects, preferences, lessons) persist across sessions and are recalled when relevant.

MCP tools

aish is MCP-native. Any capability exposed over the Model Context Protocol — file ops, git, HTTP, cloud APIs, project management — becomes a first-class tool the shell can call. Connect a server and its tools are immediately available to your intents.

This is what lets a single sentence fan out across your whole toolchain without you gluing CLIs together by hand.

Skills

Skills are expert playbooks on disk — step-by-step procedures aish reads and follows for a class of task (fixing CI, resolving merge conflicts, cutting a release, applying a design system). When a task matches a skill, aish loads it first and executes its steps with the normal toolset.

> :skill add <ref>      # install a skill
> fix the failing CI on this branch
→ matched skill: fix-ci · following playbook

Agents & background coordinators

Hand off long or parallel work to background coordinators — headless aish instances with the full toolset. They run independently, report progress, and deliver results back into your session when done.

Command	What it does
`:dispatch`	Kick off a background coordinator for a task.
`:jobs`	List running background jobs and their status.
`:attach`	Open the live worker view for a running job.
`:worker-output`	Toggle streaming a coordinator's output into your session.
`:kill`	Stop a background job.

Backends

aish runs on a hybrid brain. Lean on Claude for deep reasoning, then switch to a local model to go private and offline mid-session — one shell, cloud or local, per task.

> :backend local
→ loading Qwen3-1.7B · in-process · GGUF
✓ backend: local — offline, no API key needed

Local inference is in-process (GGUF, via mistral.rs), including tool calling. Point AISH_LOCAL_MODEL_ID at any GGUF model — no rebuild required.

Slash-command reference

Slash commands drive aish itself (as opposed to natural-language intent). The most common:

Command	Purpose
`:backend`	Show or switch the inference backend (`cloud` / `local`).
`:dispatch`	Start a background coordinator for a task.
`:jobs`	List background jobs and status.
`:attach`	Attach to a running job's worker view.
`:worker-output`	Toggle live worker output in your session.
`:kill`	Terminate a background job.
`:goal`	Set and track a longer-running goal; view status.
`:skill`	Manage skills — e.g. `:skill add <ref>`.
`:alert`	Arm an operator alert to fire when a condition is met.
`:update`	Update aish to the latest release in place.

Command surface evolves quickly toward 1.0 — this list covers the stable core. See the repo for the exhaustive, current set.

Configuration

aish is configured through environment variables:

Variable	Purpose
`ANTHROPIC_API_KEY`	API key for the cloud (Claude) backend. Not needed for local-only use.
`AISH_LOCAL_MODEL_ID`	GGUF model id to load for the local backend. Defaults to Qwen3-1.7B.

Troubleshooting

macOS: “zsh: killed aish” on launch

Gatekeeper is killing an unsigned binary. Clear the quarantine attribute or build locally from source, then retry.

Build gets OOM-killed

The heavy local-inference feature can exhaust memory on constrained machines. Build with fewer parallel jobs, or disable default features if you only need the cloud backend.

Still stuck?

Open an issue with your OS, aish version, and the command you ran.