213 lines
5.6 KiB
Markdown
213 lines
5.6 KiB
Markdown
---
|
|
slug: aish
|
|
title: AI.sh
|
|
summary: A simple shell script agent
|
|
image: https://example.com/cover.png
|
|
tags: [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):
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```sh
|
|
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`)
|
|
|
|
```sh
|
|
# 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.
|