aish/CLAUDE.md

CLAUDE.md — aish project handoff

You are continuing work on aish, an AI-augmented conversational shell implemented in LuaJIT. This file is auto-loaded when a Claude session opens a clone of this repo. Read it once at session start.

---

1. Read these first, in order

1. docs/PHASE0.md — locked substrate. Every architectural decision is here. Do not contradict it without amending it.
2. README.md — human-facing project summary and orientation.
3. config.lua — the runtime model registry. Endpoints reflect a specific LAN; the user may have already adapted yours.

If a question seems open after reading those three, ask the user a single focused question rather than guessing. Cost of asking is one turn; cost of building on a wrong assumption is half a phase.

---

2. Where you are in the phase loop

aish follows an 8(+1) phase loop:

0 substrate → 1 formulate → 2 analyze → 3 baseline → 4 plan
              → 5 review → 6 implement → 7 verify → 8 memory-update
                                                 (+1 reflect)

Loopbacks:

• 3 → 1 if baseline data invalidates the formulation
• 7 → 4 if verification fails — fix the plan, not the substrate
• any → 0 if a substrate fact turns out to be wrong

Don't skip phases. Phase 0 is done (the manifest is locked); your starting position depends on what's already in the tree.

Check the state by reading docs/ and git log --oneline. If only PHASE0.md exists in docs/ and every module raises NotImplemented, you are at Phase 0 → Phase 1 transition: the substrate is locked, no module is implemented, your job is to write the Phase 0 implementation per the manifest.

If you find phase docs docs/PHASE1.md, docs/PHASE2.md etc., follow their state.

---

3. Source-of-truth invariants — do not violate without amending PHASE0.md

These are not stylistic preferences; they are decisions that downstream phases depend on:

Invariant	Where it's locked
LuaJIT 2.x only — no PUC-Rio Lua-only constructs	§3
FFI only — no compiled C extensions, no luarocks packages	§3
Module file names in §4 are stable across phases	§4
/v1/chat/completions is the broker contract	§6
CMD: (exact prefix, single space) is the command-extraction marker	§6
Config is plain Lua loaded with dofile, not JSON/YAML	§3, §10
cd is intercepted via libc chdir, not delegated to popen	§7
Phase 0 has no disk I/O for history (memory only)	§8

If a Phase N implementation needs to break one of these, amend PHASE0.md in the same commit and call out the change in the commit message. Don't silently diverge.

---

4. Implementation order for Phase 0

Bottom-up beats top-down for this codebase. Suggested ordering:

1. ffi/libc.lua — chdir, strerror work; verifiable in isolation.
2. ffi/readline.lua — readline(), add_history(), free() work; test with a tiny REPL stub before wiring repl.lua.
3. ffi/curl.lua — easy interface, blocking POST with response capture into a Lua string. Test against any local llama-server with a curl one-liner side-by-side.
4. context.lua — pure data structure, trivial to unit-test.
5. executor.lua — popen wrapper, cd interception (uses libc.chdir), CMD: line extraction.
6. router.lua — pure function; classify(line, config) → (kind, payload).
7. broker.lua — uses ffi/curl.lua + JSON encode/decode. You will need a JSON library — see §6 below.
8. renderer.lua — output formatting; trivial.
9. repl.lua — wires everything via the dispatch table.
10. main.lua — already mostly there; finalize once repl.run exists.

Don't write all ten in one commit. One commit per module, build the chain by passing through; each commit should leave the tree in a state where luajit main.lua either runs further than the previous commit or fails with the next NotImplemented.

---

5. Testing approach

There is no test framework dependency by design. Testing is per-module ad-hoc with luajit -e 'local m = require("module"); ...' from the repo root, or a smoke luajit main.lua after each module lands.

For broker testing without burning model time: any of the local llama-servers in config.lua will respond to a hand-crafted POST. Use curl -sS http://dirac.fritz.box:8081/v1/chat/completions -d '{...}' to generate a known-good reference, then compare your FFI output.

---

6. JSON encode/decode — undecided

The manifest doesn't pick a JSON library. LuaJIT 2.x has no built-in JSON. Options:

• dkjson — pure Lua, single file, vendor it under vendor/dkjson.lua. Slow but no dependency.
• cjson — fast, but it's a C extension. Violates §3 (no compiled extensions). Skip unless you amend the manifest.
• Hand-rolled minimal encoder — viable since the broker payload shape is small and well-defined; ~50 LOC.

Recommend dkjson vendored. Decide and add a note to PHASE0.md §3 in the same commit.

---

7. When you hit ambiguity

The user (mfritsche) prefers being asked over being assumed-about. The phrase "Ask readily — prefer quick question over 3+ guessing attempts" applies. Concrete pattern:

• If the question affects only the current commit: ask.
• If it affects a future phase: log it in docs/PHASE0.md §13 (Open Questions) with target phase, keep working.
• If it affects multiple existing modules: stop, ask before refactoring.

Don't suggest pausing the session. Don't suggest "let's pick this up tomorrow". Don't pre-emptively defer work the user hasn't asked you to defer. The user controls pace.

---

8. Commit style

Imperative subject, file-scoped where possible. Examples:

• executor: implement io.popen wrapper with stderr merge
• ffi/curl: blocking POST with header list and response buffer
• repl: wire router → executor → broker dispatch
• phase0 amendment: vendor dkjson under vendor/

Body explains the why if non-obvious. Reference PHASE0.md sections by number when relevant.

Co-Authored-By trailer on Claude-authored commits:

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

(or whichever model you actually are; check before substituting.)

---

9. What aish does NOT do — out of scope, all phases

These are listed in PHASE0.md §12. Briefly:

• Does not manage llama.cpp lifecycle (assumed externally running)
• Does not implement model inference
• Is not a multiplexer (no tmux semantics)
• Is not a sandbox (no namespaces, no seccomp)

If you find yourself implementing any of those, stop — that's a different project.

---

10. The model serving aish (typically)

aish targets local llama.cpp endpoints. The committed config.lua references the user's home network (dirac.fritz.box, hossenfelder.fritz.box). The user's other Claude sessions have established that small Q4_K_M models (Qwen2.5-Coder-7B and similar) have variance issues on code generation tasks — the same prompt can yield both correct and broken code across rolls. Practical implications for aish:

• Default temperature to 0.2 or lower for code tasks.
• Don't assume the model output is correct — validate before exec.
• The confirm_cmd = true default in config.shell is there for this reason; don't disable it without a deliberate UX change.

This isn't paranoia, it's a measured property of the local model class the user runs.

---

11. Identity

If this is a session running on a fleet host other than the user's primary Claude window, your Gitea identity is claude-<hostname>. For aish (a non-PR-flow repo), commits as that identity are fine without a PR. If you need to push and lack credentials, use a Gitea Personal Access Token in the URL: git push https://<user>:<token>@git.reauktion.de/marfrit/aish.git main.

The user has marfrit-level credentials available via a separate channel if needed for repo-admin operations.

---

12. Contribution flow

Default for direct work: commit straight to main. No PR, no issue gate. This is what "non-PR-flow repo" means in §11.

Two opt-in carve-outs:

• Feature requests and bugs → Gitea issues at git.reauktion.de/marfrit/aish/issues. Don't implement feature requests in-band; file the issue, let marfrit triage. Tag architecture for cross-phase concerns. (Bug-filing convention is fleet-wide per the his cheatsheet; this row extends it to features for aish specifically.)
• Review-required iteration → PR. When the medium needs to be the diff (inline comments per finding, refinable wording), open a PR authored as claude-<host> and let marfrit review. Self-approval forbidden. PR #1 (marfrit/aish#1, 2026-05-10) set the precedent — the MCP phase-2 question batch surfaced by review of 013c625.

When in doubt whether something is a feature request vs. an in-band fix, ask. Cheaper than the alternatives.