docs: rewrite README + CLAUDE for handoff to a dedicated session
README is now self-contained for a human reader landing on the repo cold: project value-prop, status, quick-orientation reading order, directory layout, build/runtime deps, run + config invocation, and a pointer to CLAUDE.md for contribution norms. CLAUDE.md is rewritten as the substrate a fresh Claude session needs to pick up Phase 0→1 implementation without prior conversation context: - Reading order (PHASE0.md → README → config.lua) - Phase-loop discipline (8+1 with loopbacks) - Eight invariants from PHASE0.md called out as non-negotiable without manifest amendment - Bottom-up implementation order for Phase 0 (libc → readline → curl → context → executor → router → broker → renderer → repl → main) - Testing approach without a test framework - Open question on JSON library (dkjson recommended; needs §3 amendment) - Ambiguity handling pattern (ask vs log-in-§13 vs stop-and-ask) - Commit style + Co-Authored-By trailer template - Model-class caveat: small Q4 coder models have output variance, validate before exec, confirm_cmd defaults exist for this reason - Push credential note for sessions without ssh-keys-on-Gitea Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -2,35 +2,118 @@
|
||||
|
||||
**aish** — AI-augmented conversational shell.
|
||||
|
||||
A unified REPL backed by language models accessed through a llama.cpp broker.
|
||||
Shell execution, AI inference, context management, and session memory in one
|
||||
terminal interface.
|
||||
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.
|
||||
|
||||
Implementation: LuaJIT 2.x with FFI bindings (libcurl, GNU readline, libc),
|
||||
no compiled extensions, no build step.
|
||||
## 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
|
||||
|
||||
**Pre-implementation.** Phase 0 manifest only — see
|
||||
[`docs/PHASE0.md`](docs/PHASE0.md) for the full substrate, scope, technology
|
||||
decisions, directory layout, dispatch model, broker contract, execution
|
||||
model, configuration, and planned phase sequence.
|
||||
| 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
|
||||
|
||||
See `docs/PHASE0.md` §4. File names are stable across phases — later phases
|
||||
fill in module bodies, they do not rename files.
|
||||
```
|
||||
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
|
||||
|
||||
Not runnable yet. Once Phase 0 lands:
|
||||
Once Phase 0 ships:
|
||||
|
||||
```sh
|
||||
luajit main.lua [--config <path>]
|
||||
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
|
||||
|
||||
This repo follows the 8(+1) phase loop documented in mfritsche's home-project
|
||||
canon (`feedback_dev_process.md` in claude-noether memory). Each phase has its
|
||||
own document under `docs/`. The Phase 0 manifest is the locked substrate.
|
||||
See [`CLAUDE.md`](CLAUDE.md) for contribution conventions, commit style,
|
||||
and the phase-loop discipline this project follows.
|
||||
|
||||
Reference in New Issue
Block a user