Getting Started

Install aish in 5 minutes.

Prerequisites

aish is written in Rust and runs on Linux and macOS. You'll need:

  • An ANTHROPIC_API_KEY for the default Claude backend — free at console.anthropic.com. (Or run fully offline with --backend local.)
  • A Rust toolchain (rustup) if building from source.

Installation

$ git clone https://github.com/LightHeart-Ventures/aish
$ cd aish
$ make install        # builds --release and installs the binary

Without make:

$ cargo build --release   # binary at ./target/release/aish

Then configure your API key (add to your shell profile to persist):

$ export ANTHROPIC_API_KEY=sk-ant-...

Your First Command

Start the interactive REPL:

$ aish

Type a natural-language intent:

> 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)

aish classifies the line, invokes tools as needed, and streams results. Routine commands (git status, ls, anything on your PATH) run directly — no model, no latency. Only genuine intent engages the agent.

Offline Mode

No API key? Run the built-in local backend (first launch downloads a hardware-appropriate GGUF model, ~4 GB):

$ aish --backend local

Key Concepts

  • Intent — natural language → aish parses and executes.
  • Routing — :command / direct-exec / agent / ! · ? escape hatches.
  • Tools & MCP — file ops, git, and remote capabilities exposed via MCP servers.
  • Coordinators — background agents (:dispatch) that run deferrable work with the full toolset and survive restarts.
  • Skills — expert playbooks on disk (:skill) the agent reads and follows.
  • Goals & Memory — durable, cross-session objectives and facts in ~/.aish.

Next Steps