aish/README.md

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 2 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 — 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 2+)
├── 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:

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 for contribution conventions, commit style, and the phase-loop discipline this project follows.