# aish

**aish** — AI-augmented conversational shell.

A single REPL that interleaves shell command execution and language-model
conversation, backed by a llama.cpp HTTP broker. Implementation is LuaJIT
2.x with FFI bindings to libcurl, GNU readline, and libc — no C extensions,
no build step, one source tree.

## Why

Three flows that currently live in three windows fold into one:

1. **"Run this command and show me the output"** — fast feedback loop, no
   copy-paste between terminal and chat.
2. **"Explain or write code based on the output we just looked at"** —
   exec output is automatically injected into the model's context.
3. **"Plan and execute a multi-step task with confirmation gates"** —
   landing in Phase 3 as Chuck Norris autonomous mode.

aish is not a wrapper around bash. It's a first-class interactive
environment where the shell is one of several execution channels.

## Status

| Component | State |
|---|---|
| Repository skeleton | ✅ in this commit |
| Phase 0 manifest | ✅ [`docs/PHASE0.md`](docs/PHASE0.md) — locked |
| Phase 0 implementation | 🔜 next session |
| Phase 1+ | 📋 enumerated in PHASE0.md §11 |

Every module file currently raises `not implemented (Phase 0 pending)`
when called. `luajit main.lua` fails loudly at the first un-implemented
function, never silently.

## Quick orientation

| Read this | If you want to know |
|---|---|
| `docs/PHASE0.md` §1–2 | What aish is and what Phase 0 ships |
| `docs/PHASE0.md` §3 | Technology decisions (LuaJIT, FFI, readline, libcurl, llama.cpp) |
| `docs/PHASE0.md` §4 | Directory layout — these file names are stable across all phases |
| `docs/PHASE0.md` §5 | How input is dispatched (meta / shell / AI) |
| `docs/PHASE0.md` §6 | Broker contract: `/v1/chat/completions`, `CMD:` extraction |
| `docs/PHASE0.md` §10 | Config schema and resolution order |
| `docs/PHASE0.md` §11 | Phase sequence (what lands when) |
| `docs/PHASE0.md` §13 | Open questions, tracked per phase |
| `CLAUDE.md` | Project conventions for AI-assisted contributors |

## Directory layout

```
aish/
├── main.lua              # entry point
├── repl.lua              # readline loop, dispatch, prompt
├── broker.lua            # llama.cpp HTTP client
├── router.lua            # input classifier (meta/shell/AI)
├── executor.lua          # command exec + CMD: extraction
├── context.lua           # in-memory turn history
├── history.lua           # disk persistence (Phase 1+)
├── safety.lua            # destructive-op gate (Phase 3+)
├── renderer.lua          # output formatting
├── config.lua            # default model registry + preferences
├── ffi/
│   ├── curl.lua          # libcurl easy interface
│   ├── readline.lua      # GNU readline
│   ├── pty.lua           # forkpty (Phase 1+)
│   └── libc.lua          # chdir, errno, strerror
└── docs/
    └── PHASE0.md         # locked substrate
```

## Build / runtime dependencies

System packages (Debian / ALARM / Arch names):

- `luajit` (>= 2.0)
- `libcurl4` / `libcurl-openssl-3` runtime
- `libreadline8` runtime
- `libc6` runtime (always present)

No compilation, no `luarocks`, no `make`. Just `luajit main.lua`.

## Running

Once Phase 0 ships:

```sh
luajit main.lua                          # uses ~/.config/aish/config.lua
luajit main.lua --config ./config.lua    # explicit config path
AISH_CONFIG=/path/to/config.lua luajit main.lua
```

Config resolution order is documented in `docs/PHASE0.md` §10.

## Configuration

`config.lua` is a Lua file returning a single table. The committed
`config.lua` in this repo is both the canonical example and the
development-fallback config (lowest precedence). Copy it to
`~/.config/aish/config.lua` and edit endpoints to your local llama.cpp
servers, or point `AISH_CONFIG` at your own.

The default endpoints assume mfritsche's home network:
- `fast` → `dirac.fritz.box:8081` (Qwen2.5-Coder-7B q4 8k ctx)
- `deep` → `dirac.fritz.box:8080` (Qwen2.5-Coder-7B q4 32k ctx)
- `cloud` → `hossenfelder.fritz.box:8082` (forwards to OpenRouter)

Replace these with your own llama.cpp endpoints if you're not on that LAN.

## License

Not yet selected. Default-private until decided.

## Project conventions

See [`CLAUDE.md`](CLAUDE.md) for contribution conventions, commit style,
and the phase-loop discipline this project follows.