| 💾 Saved. d722711 k33g 3h ago | 1 | # mini-me (mm) — project summary |
| 2 | |
| 3 | ## What it is |
| 4 | |
| 5 | A minimal Go coding agent (`module mm`, Go 1.25 in `go.mod`, builds with Go 1.26.5) that drives a local LLM through the OpenAI-compatible chat-completions API with Genkit (`github.com/firebase/genkit/go` v1.10.0). Two front ends share one loop: a terminal REPL (`internal/agent`) and an Agent Client Protocol façade (`internal/acp`, `github.com/coder/acp-go-sdk` v0.13.5) selected with `mm -acp`. |
| 6 | |
| 7 | ## Architecture (verified 2026-09-15) |
| 8 | |
| 9 | `main.go` does the wiring only. Packages under `internal/`: `config` (defaults + YAML + `AGENT_*` env overrides), `engine` (provider registry `dmr`/`llamacpp`, streaming, watchdog, non-streaming retry, `Summarize`), `tools` (`bash`, `read_skill`, `read_file`, `write_file`, `edit_file`), `fileedit` (exact-replacement editing), `skills` (catalogue from `<skillsDir>/*.md` front matter), `detector` (repeated-action detection), `compact` (history compression), `spinner`, `ui` (`Out` writer + `Sink` event interface the ACP façade implements), `agent`, `acp`, `session` (added 2026-09-15 by the `/new` work — see history). |
| 10 | |
| 11 | ## Commands |
| 12 | |
| 13 | | Purpose | Command | |
| 14 | |---------|---------| |
| 15 | | Build | `go build -o mm .` | |
| 16 | | Install | `./install.sh` (builds, copies to `/usr/local/bin`) | |
| 17 | | Test | `go test ./...` | |
| 18 | | Run (DMR) | `./mm` (reads `./agent.yaml`) | |
| 19 | | Run (llama.cpp) | `./mm agent.llamacpp.yaml` | |
| 20 | | Editor | `mm -acp` with `AGENT_CONFIG=<absolute path>` | |
| 21 | | Quality gate | `python3 ~/.claude/skills/quality/scripts/quality_report.py --workspace .` (report under `.quality/`, exit 0 = pass) | |
| 22 | |
| 23 | Use `bash -l -c "…"` in this sandbox so `go` is on the PATH. |
| 24 | |
| 25 | ## Decisions in force |
| 26 | |
| 27 | - Tools return failures as text, never as Go errors (the model must read them). |
| 28 | - Full history is kept after a failed/cancelled turn; only an unanswered question is dropped. |
| 29 | - One provider type per wire protocol (`openaiCompat`); `dmr` and `llamacpp` are registry entries. |
| 30 | - API keys are named by environment variable in YAML, never stored in it. |
| 31 | - `contextWindow` is one top-level key shared by the banner and the compression trigger. |
| 32 | - Documentation follows Diátaxis, bilingual: `docs/en/` and `docs/fr/` with identical file names; `kits/` and `tmp/` are out of scope. |
| 33 | - Slash commands: terminal `/quit`, `/abort`, `/compact`, `/new`; ACP `/new`, `/compact` only (no `/quit`: the editor owns the process; no `/abort`: Escape in Zed cancels through `session/cancel` — user's decision 2026-09-15, an earlier `/abort` was removed), advertised through `available_commands_update` sent right AFTER the `session/new` response is written (a hook on the writer handed to the SDK, `responseWriter` in `internal/acp/acp.go`, fires when the response line carrying the session id goes out). Sending it before the response does not work: Zed drops updates for a session id it has not received yet (user report 2026-09-15; fix confirmed working in Zed by the user). Only what `session/prompt` intercepts is advertised. `/new` and `/compact` are intercepted under `turnMu`, so the history never moves under Genkit. The compaction report line is `compact.Result.Report()`, shared by both front ends. |
| 34 | - `/new` resets the history (system prompt alone), the engine's last input-token count, and — terminal only — the loop detector (`detector.Reset`): a new session is a new task, unlike `/compact` which keeps the detector. Over ACP it keeps the session id, `cwd` and "allow always" grants. Shared logic lives in `internal/session`, imported as `history` inside `internal/acp` (name clash with its `session` struct). |
| 35 | - Quality gate scope: `.qlty/qlty.toml` excludes `kits/**` and `tmp/**` (user's request, 2026-09-15), drops qlty's default `**/config/**` exclusion so `internal/config` is measured, and enables `gofmt`, `golangci-lint`, `osv-scanner` by hand (`qlty init` only saw tracked files, hence no Go). Do not re-run `qlty init`. |
| 36 | - Zed `agent_servers` entry for mm must carry `"type": "custom"` alongside `command`/`args`/`env`; without it Zed rejects the entry (user report, 2026-09-15). Both `how-to/use-from-an-editor.md` pages show the full block. |
| 37 | - Skills: two layouts, flat `<name>.md` and `<name>/SKILL.md` (Agent Skills convention, the shipped one); `Read` prefers the flat file. A relative `skillsDir` is made absolute in `main.go` (`resolveSkillsDir`): from the current directory (terminal, or ACP without a config file) or next to the config file (ACP with one); the banner warns `no skills found in <abs path>` when the count is 0. |
| 38 | - `@path` mentions (`internal/mention`, `Expand(input, cwd)`): a typed `@path` that exists (relative to the start directory / session cwd, absolute, or `~/`) appends `[attached file: <abs>]` / `[attached directory: <abs>]` to the message — the exact shape of an ACP `resource_link` — and is echoed (`📎` line in the terminal, `[acp] … attached` on stderr). No picker, no completion, content never inlined; a non-existing path or a `@` glued to a word is left alone. Used by both front ends. |
| 39 | - The package import graph is kept in `docs/diagrams/packages.drawio` (generated from `go list`); update it when a package is added, removed or re-wired. |
| 40 | |
| 41 | ## Known defects (verified 2026-09-15, not fixed) |
| 42 | |
| 43 | - None open. (The skills-layout bug and the `demo/skills` test path were fixed on 2026-09-15; `go test ./...` passes.) |
| 44 | |
| 45 | ## Quality gate state (2026-09-15, 2 runs in `.quality/history.jsonl`) |
| 46 | |
| 47 | FAIL on pre-existing debt only: 67 warnings (55 `osv-scanner` on `go.mod` — 47 against `stdlib@1.25.0`, i.e. the `go` directive, 8 against indirect deps `jsonparser`, `otel`, `x/sys`; 12 `golangci-lint:errcheck` in `main.go`, `internal/engine`, `internal/fileedit`) and 18 smells (complexity: `agent.Run` = 121, `fileedit/diff.go`, `compact.Valid`, `engine.Generate`, `config.validate`, `engine.Explain`). No finding in the `/new` code. |
| 48 | |
| 49 | ## Repository oddities |
| 50 | |
| 51 | - Almost everything is untracked in git (only two commits, "Updated."). `.gitignore` exists. |
| 52 | - `.tickets/` (IssueSpec) holds three open issues: add a help command, add an about command, improve TUI. |
| 53 | - `agent.yaml` names the agent "Bob" in its system prompt; ACP `agentInfo.name` is also `bob`, version `0.11.0`. The binary is `mm`. |
| 54 | |
| 55 | ## Not yet established |
| 56 | |
| 57 | - Whether a real DMR or llama-server run works end to end from this sandbox (no model server here; only the banner and `-h` were exercised). |
| 58 | - Whether the project wants `go.mod`'s `go 1.25.0` bumped to 1.26 and the flagged indirect deps upgraded to clear the osv-scanner findings. |