slug, title, summary, image, tags

slug	title	summary	image	tags
aish	AI.sh	A simple shell script agent	https://example.com/cover.png	ai agent aiharness

aish

           ,     ,
          (\____/)
           (_oo_)
             (O)        --  ai.sh
           __||__    \)
        []/______\[] /
        / \______/ \/
       /    /__\
      (\   /____\

Idea

How simple, lightweight and reliable can an agent be?

Solution

• One shell script.
• Use tried and tested linux programs like curl and jq.
• Log file is simple so you can read it, and it is used for agent context.
• Just give the agent shell access. No special commands, no context bloat.
• Fast
• This repo has 2 files.

Usage

Ask the agent a question (no quotes needed for simple text):

./ai.sh what is the capital of Japan?
./ai.sh -v what is 2 plus 2
./ai.sh -m gpt-4o "write a hello world program in python. save it in ~/"

The agent can run shell commands, read files, and execute multi-step tasks. Context is saved and resumed on subsequent calls.

Command mode

Describe a command in English. The LLM generates the shell command, prints it, and runs it in your terminal:

./ai.sh -c show me all files including hidden ones
./ai.sh -c find all python files modified this week
./ai.sh -c show me disk usage sorted by size

Autonomous mode

Give the agent a goal and let it run until done or budget exhausted:

./ai.sh -a "explore the codebase and summarize the architecture"

Initialize a local agent

By default, aish stores everything globally in ~/.aish/. To create a self-contained agent for a specific project:

./ai.sh -i

This creates a .aish/ directory in the current folder with its own config, system prompt, and log. While .aish/ exists, all storage is local to that directory. Remove it to return to global mode.

Piping

The agent's answer goes to stdout; status messages go to stderr. So you can pipe the answer into other commands:

./ai.sh what is the capital of Japan | wc -w
./ai.sh list all python files in this dir | grep test
./ai.sh what is 2+2 > answer.txt

You can also pipe input in. If no message is given on the command line, stdin becomes the message. If both are given, stdin is appended:

echo "explain this error" | ./ai.sh
cat error.log | ./ai.sh explain this error
git diff | ./ai.sh -c generate a commit message

Quick start

# 1. Install dependencies
sudo apt install curl jq coreutils    # Debian/Ubuntu

# 2. Add your API key (get one from https://ppq.ai)
cat > ~/.aish.conf <<'EOF'
DEFAULT_API_KEY="sk-your-key-here"
EOF
chmod 600 ~/.aish.conf

# 3. Run it
./ai.sh what is the capital of Japan

That's it. No build step, no install script, no daemon.

Options

Short	Long	Description
-c	--cmd	Command mode (generate and run a shell command)
-a	--autonomous	Autonomous mode (run until done or budget exhausted)
-i	--init	Create local .aish/ with defaults, exit
-x	--clear	Clear the log file and exit
-v	--verbose	Show status lines
-m	--model	Override model
-k	--api-key	API key (or set PPQ_API_KEY)
-C	--max-cost	Override max cost (USD)
-s	--max-steps	Override max steps
-t	--timeout	Override overall timeout (seconds)
-T	--cmd-timeout	Override per-command timeout (seconds)
-r	--resume	Resume from existing log (default: yes)
-R	--no-resume	Start fresh (ignore existing log)
-h	--help	Show help

Configuration

API key

Create ~/.aish.conf with your key:

cat > ~/.aish.conf <<'EOF'
DEFAULT_API_KEY="sk-your-key-here"
EOF
chmod 600 ~/.aish.conf

This file lives in your home directory, outside the repo, and is never committed. Any DEFAULT_* variable from ai.sh can be overridden there.

Config priority

Settings are resolved in this order (first match wins):

1. CLI flags (-m, -C, -s, etc.)
2. Local .aish/config.json (if .aish/ exists in current directory)
3. Global ~/.aish/config.json
4. ~/.aish.conf shell vars
5. Built-in defaults in ai.sh

Storage

Global mode (default): ~/.aish/ holds config, system prompt, and log. The agent has shared global memory — conversations from any directory are logged to the same file and resumed on subsequent calls.

Local mode: Run ./ai.sh -i to create a .aish/ in the current directory. While it exists, that directory uses its own config, prompt, and log instead of the global ones.

Dependencies

• curl
• jq
• coreutils (date, mkdir, chmod, head, cat, printf, mktemp, timeout, sync, basename, sleep, wc, tail, sed, grep)

# Debian / Ubuntu
sudo apt install curl jq coreutils

# Fedora / RHEL
sudo dnf install curl jq coreutils

# Arch
sudo pacman -S curl jq coreutils

# macOS (Homebrew — coreutils provides GNU versions like `timeout`)
brew install curl jq coreutils

Log format

Each line in log.jsonl is JSON with a source field:

source	event	who
user	user_input	you
model	response	the AI
aish	exec	script ran a command
aish	api_error	script detected an error

Warning

This agent has full shell access. It can run any command on your system — read files, write files, delete data, install software, make network requests. There are no sandboxing or permission restrictions.

Run it only on a computer, VM, or Qube that is dedicated to agent use. Do not run it on a machine with sensitive data or credentials you cannot afford to lose.