mimic-llm 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +21 -0
  3. data/NOTICE +16 -0
  4. data/README.md +175 -0
  5. data/exe/lllm +5 -0
  6. data/exe/llm +5 -0
  7. data/exe/mimic +5 -0
  8. data/lib/mimic/README.md +144 -0
  9. data/lib/mimic/agent/claude.rb +305 -0
  10. data/lib/mimic/agent/codex.rb +254 -0
  11. data/lib/mimic/agent/codex_fallback_prompt.md +275 -0
  12. data/lib/mimic/agent/hermes.rb +107 -0
  13. data/lib/mimic/agent/muse.rb +106 -0
  14. data/lib/mimic/agent.rb +46 -0
  15. data/lib/mimic/cli.rb +159 -0
  16. data/lib/mimic/client/base.rb +44 -0
  17. data/lib/mimic/client/crush.rb +28 -0
  18. data/lib/mimic/client/goose.rb +52 -0
  19. data/lib/mimic/client/hermes.rb +21 -0
  20. data/lib/mimic/client/opencode.rb +29 -0
  21. data/lib/mimic/client/pi.rb +50 -0
  22. data/lib/mimic/client.rb +19 -0
  23. data/lib/mimic/engine/README.md +140 -0
  24. data/lib/mimic/engine/base.rb +138 -0
  25. data/lib/mimic/engine/chat_template.rb +207 -0
  26. data/lib/mimic/engine/ik_llama.rb +273 -0
  27. data/lib/mimic/engine/launcher.rb +25 -0
  28. data/lib/mimic/engine/llama.rb +124 -0
  29. data/lib/mimic/engine/llama_embed.rb +108 -0
  30. data/lib/mimic/engine/router.rb +57 -0
  31. data/lib/mimic/engine/server_process.rb +108 -0
  32. data/lib/mimic/engine.rb +5 -0
  33. data/lib/mimic/engine_cli/binary_options.rb +46 -0
  34. data/lib/mimic/engine_cli/builder.rb +98 -0
  35. data/lib/mimic/engine_cli/diffusion.rb +117 -0
  36. data/lib/mimic/engine_cli/llama_preset.rb +119 -0
  37. data/lib/mimic/engine_cli/registry.rb +94 -0
  38. data/lib/mimic/engine_cli/source.rb +110 -0
  39. data/lib/mimic/engine_cli/status.rb +161 -0
  40. data/lib/mimic/engine_cli/update.rb +68 -0
  41. data/lib/mimic/engine_cli.rb +7 -0
  42. data/lib/mimic/health/checks.rb +92 -0
  43. data/lib/mimic/health.rb +82 -0
  44. data/lib/mimic/llm_cli/base.rb +36 -0
  45. data/lib/mimic/llm_cli/configure.rb +84 -0
  46. data/lib/mimic/llm_cli/embed.rb +80 -0
  47. data/lib/mimic/llm_cli/engines.rb +44 -0
  48. data/lib/mimic/llm_cli/models.rb +31 -0
  49. data/lib/mimic/llm_cli/models_table.rb +119 -0
  50. data/lib/mimic/llm_cli/paths.rb +48 -0
  51. data/lib/mimic/llm_cli/root.rb +215 -0
  52. data/lib/mimic/llm_cli/wizard/context_preflight.rb +82 -0
  53. data/lib/mimic/llm_cli/wizard/embed.rb +89 -0
  54. data/lib/mimic/llm_cli/wizard/moe.rb +82 -0
  55. data/lib/mimic/llm_cli/wizard/parallel.rb +76 -0
  56. data/lib/mimic/llm_cli/wizard/setup.rb +211 -0
  57. data/lib/mimic/llm_cli.rb +5 -0
  58. data/lib/mimic/llm_config/embed.rb +48 -0
  59. data/lib/mimic/llm_config/llama_settings.rb +60 -0
  60. data/lib/mimic/llm_config/model_settings.rb +84 -0
  61. data/lib/mimic/llm_config/sampling.rb +54 -0
  62. data/lib/mimic/llm_config/settings.rb +92 -0
  63. data/lib/mimic/llm_config.rb +132 -0
  64. data/lib/mimic/model/footprint.rb +303 -0
  65. data/lib/mimic/model/gguf.rb +204 -0
  66. data/lib/mimic/model/header.rb +169 -0
  67. data/lib/mimic/model/library.rb +132 -0
  68. data/lib/mimic/model/memory.rb +126 -0
  69. data/lib/mimic/model/store.rb +46 -0
  70. data/lib/mimic/model/upstream.rb +81 -0
  71. data/lib/mimic/model.rb +116 -0
  72. data/lib/mimic/paths.rb +45 -0
  73. data/lib/mimic/result.rb +8 -0
  74. data/lib/mimic/ui.rb +89 -0
  75. data/lib/mimic/util/fmt.rb +15 -0
  76. data/lib/mimic/util/hf.rb +55 -0
  77. data/lib/mimic/util/host.rb +95 -0
  78. data/lib/mimic/util/probes.rb +255 -0
  79. data/lib/mimic/version.rb +3 -0
  80. data/lib/mimic.rb +22 -0
  81. metadata +186 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 46e0ec34752f372cb8d8c07ab096ca407f27ba5e30abb6ee51cbef9ee24f579a
4
+ data.tar.gz: 499297fcc4dd6bbd42c65aebed77ee4e8f653f65946f209b4e0d71c692cdb043
5
+ SHA512:
6
+ metadata.gz: '08249511e1cf767cf2fa0b6592d58a4cf61e135020b4995cb09823b5364a22ac81dc6e887c3a0e6ef1f0b57aca290368dfc384fac0bd7cec1a0cb109bcc950d5'
7
+ data.tar.gz: 7167caab8a1a130640d6eb4aeed3eed7af8234e4119ff12d5eedb8bcc91cf0a337237d40a80dd6c741abe5416a20f08a66f416920d324048e216aa858e02aa5b
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 raykin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/NOTICE ADDED
@@ -0,0 +1,16 @@
1
+ mimic-llm bundles one file it did not write:
2
+
3
+ lib/mimic/agent/codex_fallback_prompt.md
4
+
5
+ It is a verbatim copy of the Codex CLI system prompt, taken from
6
+ unslothai/unsloth (unsloth_cli/codex_fallback_prompt.md), which in turn carries
7
+ it from OpenAI's Codex CLI. Both projects are licensed under the Apache License
8
+ 2.0:
9
+
10
+ https://www.apache.org/licenses/LICENSE-2.0
11
+
12
+ The file is unmodified. `Mimic::Agent::Codex` reads it as the `base_instructions`
13
+ of the model catalog entry it writes for Codex, because a local llama.cpp server
14
+ has no hosted backend to supply them.
15
+
16
+ The rest of mimic-llm is MIT licensed -- see LICENSE.
data/README.md ADDED
@@ -0,0 +1,175 @@
1
+ # mimic-llm
2
+
3
+ `llm` manages local llama.cpp, ik_llama.cpp, and PrismML llama.cpp servers. `mimic` launches Claude
4
+ Code or Codex against it, so a local model answers instead of a hosted one.
5
+
6
+ ## Requirements
7
+
8
+ - **Linux**, **Ruby 3.2+**, and an NVIDIA or AMD GPU.
9
+ - **`claude` or `codex`** installed, for the launcher you want.
10
+ - Everything else -- the inference engine included -- `llm setup` handles.
11
+
12
+ ## From nothing to a local Claude Code
13
+
14
+ gem install mimic-llm
15
+
16
+ Get one GGUF model file. This is the only step `llm` cannot do for you; it
17
+ downloads nothing. Any `.gguf` works, and unsloth publishes ready ones:
18
+
19
+ pip install huggingface_hub
20
+ hf download unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF \
21
+ --include "*UD-Q4_K_XL*" --local-dir ~/models
22
+
23
+ Then:
24
+
25
+ llm setup
26
+
27
+ It checks the box (RAM, disk, GPU backend, whether `llama-server` and `claude`
28
+ are already there), asks which engine to use, and **clones and builds it when no
29
+ binary exists** -- a CUDA build takes 10-30 minutes and needs `git`, `cmake`,
30
+ `cc`, `c++`. It then scans for GGUFs, and offers to type a path when it finds
31
+ none. Point it at `~/models`, or register the directory once with
32
+ `llm path add ~/models` so later runs list it.
33
+
34
+ The remaining steps pick a context length and whether the model thinks before
35
+ answering. Context is checked against your card's free VRAM before it is
36
+ accepted, so an oversized choice is rejected at the prompt rather than at a
37
+ failed launch. Settings land in `~/.llm/config.yaml`, and setup offers to start
38
+ the server.
39
+
40
+ llm status
41
+
42
+ Confirms the server is up, on `http://127.0.0.1:8080` by default, and prints
43
+ what it loaded. Then:
44
+
45
+ mimic claude
46
+
47
+ Claude Code, answered by your own model. `mimic codex` does the same for Codex.
48
+
49
+ To change anything later: `llm setup` again, or `llm config` for one value,
50
+ then `llm restart`.
51
+
52
+ `llm engines` lists all three engines with their source, branch, checkout,
53
+ revision, and binary. `llm engines update` fetches all three and rebuilds any
54
+ that are behind; restart the server to use a rebuilt binary.
55
+
56
+ If something else already owns `llm` on your `PATH` (the python `llm` CLI, most
57
+ often), the gem installs `lllm` as the same program under a free name.
58
+
59
+ ## State it owns
60
+
61
+ | Path | Contents |
62
+ | --- | --- |
63
+ | `~/.llm` | engine side: `config.yaml`, checkouts, presets, chat templates, sidecar stores, `run/` (logs, launch records) |
64
+ | `~/.mimic` | agent side: isolated agent homes under `agents/`, the `bin/` PATH shim, `mcp-servers.json` |
65
+ | `/tmp/llm` | pid files for the running servers |
66
+
67
+ Neither engine claims a home directory of its own, so `~/.llm` is this gem's to
68
+ define.
69
+
70
+ ## Paths it assumes rather than discovers
71
+
72
+ These are hardcoded. Nothing probes for them, and nothing errors when they are
73
+ absent — the feature that depends on one silently finds nothing.
74
+
75
+ **Models.** The default search paths are `~/hf-models`, `~/.llm/models` and
76
+ `~/.lmstudio/models`. Add your own with `llm path add DIR`; the list lives in
77
+ `~/.llm/config.yaml` and the defaults are only the starting point.
78
+ `Model::Upstream` also treats `~/.lmstudio/models` as the layout that names a
79
+ model's source repo, so `llm models check` reports `?` for models stored any
80
+ other way whose GGUF header names no repo either.
81
+
82
+ **Engine binary.** Each engine has its own ordered resolution list — for
83
+ llama.cpp: `llama-server` on `PATH`, then its checkout at
84
+ `~/.llm/llama.cpp/build/bin/llama-server`, then `~/.local/bin/llama-server`.
85
+ ik_llama.cpp prefers its own build over `PATH`. The current
86
+ `prism-v7-llama.cpp` accepts only its own build, since its ternary formats
87
+ need Prism kernels. `llm setup` clones and builds into `~/.llm`.
88
+
89
+ **Client configs.** `llm sync` pushes the active model alias and context length
90
+ into whichever of these already exist, and skips the rest:
91
+
92
+ | Client | File |
93
+ | --- | --- |
94
+ | crush | `~/.config/crush/crush.json` |
95
+ | opencode | `~/.config/opencode/opencode.jsonc` |
96
+ | goose | `~/.config/goose/config.yaml` (+ `custom_providers/llamacpp.json`) |
97
+ | pi | `~/.pi/agent/models.json`, `settings.json` |
98
+ | hermes | `~/.hermes/config.yaml` |
99
+
100
+ An existing config file is the only evidence a client is installed — goose in
101
+ particular gets nothing written unless its config is already there. `opencode`
102
+ is skipped, with a warning, when its `.jsonc` carries comments, since rewriting
103
+ it as JSON would drop them.
104
+
105
+ **Agent binaries.** `mimic claude` and `mimic codex` resolve `claude` and
106
+ `codex` on `PATH` and abort with an install hint when either is missing
107
+ (`MIMIC_ALLOW_INSTALL=1` lets codex through so its own installer can run).
108
+ `mimic hermes-lcc` wants `hermes`, which `mimic install-hermes` puts in an
109
+ isolated venv at `~/.hermes/venv`. All three also require llama-server to be
110
+ up, and say so rather than failing at the first request.
111
+
112
+ ## MCP servers (opt-in)
113
+
114
+ `mimic claude` runs Claude Code against a config dir of its own, and wires in
115
+ whatever `~/.mimic/mcp-servers.json` names — Claude Code's own `mcpServers`
116
+ shape, merged into that dir's `.claude.json` without touching entries you added
117
+ by hand:
118
+
119
+ ```json
120
+ {
121
+ "c4ai": { "command": "python", "args": ["-m", "c4ai_mcp.fastmcp_server"] }
122
+ }
123
+ ```
124
+
125
+ No file means no servers. The gem ships none and picks none for you.
126
+
127
+ `WebSearch` and `WebFetch` are denied regardless. They are Anthropic
128
+ server-executed tools; llama.cpp's `/v1/messages` bridge has no implementation
129
+ (`unsupported Responses tool type 'web_search'` in the server log) and returns
130
+ zero results rather than failing. Denying them makes that visible. An MCP server
131
+ is how you give the model internet access instead. Whatever you name has to be
132
+ runnable on its own — nothing in the example above ships with this gem.
133
+
134
+ ## Development
135
+
136
+ ```
137
+ bundle install && bundle exec rspec < /dev/null
138
+ ```
139
+
140
+ The `< /dev/null` is required: one spec exercises cli-ui's prompt layer, which
141
+ opens Reline against the terminal and blocks forever when stdin is a tty.
142
+
143
+ To run a checkout instead of the installed gem, symlink `exe/llm` and
144
+ `exe/mimic` onto your `PATH` -- they run under plain `ruby`, so the gem
145
+ dependencies have to be on the default gem path.
146
+
147
+ The suite runs under `spec/support/real_llm_root_guard.rb`, which raises on any
148
+ write or delete under `~/.llm`, `~/.mimic`, `/tmp/llm` or a client config tree.
149
+ Point a `stub_const` at a tmpdir instead.
150
+
151
+ ## Trademarks
152
+
153
+ Not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI or unsloth.
154
+ "Claude", "Claude Code", "Codex" and "OpenAI" are trademarks of their respective
155
+ owners, used here only to describe what this tool interoperates with.
156
+
157
+ This project ships neither client. `mimic` launches `claude` or `codex` if you
158
+ have installed them yourself, and configures them through their own documented
159
+ settings -- `ANTHROPIC_BASE_URL` for Claude Code, `model_providers` for Codex.
160
+ No Anthropic or OpenAI credential is used or required; `Agent::Claude` unsets
161
+ `ANTHROPIC_API_KEY` and `CLAUDE_CODE_OAUTH_TOKEN` before launching. Your use of
162
+ either client remains governed by its own license and terms.
163
+
164
+ Design credit: the Claude Code and Codex launch recipes are reimplementations of
165
+ [unsloth](https://github.com/unslothai/unsloth)'s `unsloth_cli/start.py`. What
166
+ was taken and what was deliberately left is recorded in `UPSTREAM-REVIEW.md`.
167
+ The Codex provider block mimic writes still carries unsloth's own profile name
168
+ (`unsloth_api`) and auth env var, so an existing `~/.codex/config.toml` keeps
169
+ working.
170
+
171
+ ## License
172
+
173
+ MIT -- see [LICENSE](LICENSE). One bundled file is not MIT:
174
+ `lib/mimic/agent/codex_fallback_prompt.md` is a verbatim Apache-2.0 copy of the
175
+ Codex CLI system prompt, carried from unsloth. See [NOTICE](NOTICE).
data/exe/lllm ADDED
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env ruby
2
+ require_relative "../lib/mimic"
3
+ require_relative "../lib/mimic/llm_cli"
4
+
5
+ Mimic::LlmCli::Root.start(ARGV)
data/exe/llm ADDED
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env ruby
2
+ require_relative "../lib/mimic"
3
+ require_relative "../lib/mimic/llm_cli"
4
+
5
+ Mimic::LlmCli::Root.start(ARGV)
data/exe/mimic ADDED
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env ruby
2
+ require_relative "../lib/mimic"
3
+ require_relative "../lib/mimic/cli"
4
+
5
+ Mimic::Cli.new(ARGV).run
@@ -0,0 +1,144 @@
1
+ # Mimic — design rules and traps
2
+
3
+ Conventions the whole library is written to, and the mistakes it has already
4
+ made. `engine/README.md` covers the engine namespaces specifically.
5
+
6
+ ## Design rules
7
+
8
+ - **Objects, not modules of free functions.** If the same argument is threaded
9
+ through most functions in a file (`cfg`, `client`, `path`), that argument is
10
+ the object: make it a class, take it in `initialize`, drop it from every
11
+ signature. A helper module is for genuinely stateless helpers with no shared
12
+ subject — these live under `Mimic::Util` (`Util::Fmt`, `Util::Probes`,
13
+ `Util::Host`).
14
+ - **`module_function` is banned; use `class << self`.** Under `module_function`
15
+ a plain `private` does not touch the singleton methods callers actually
16
+ reach, so "every class declares its private surface" is unexpressible. It is
17
+ also a mode switch — a method below the macro silently becomes a module
18
+ function, one above silently does not — and it leaves a private
19
+ instance-method twin of everything that an `include` would inject.
20
+ - **`cfg` belongs in an ivar**, set once in `initialize`, not recomputed at
21
+ every call site or passed down a call chain.
22
+ - **Config is read through its section object, never a flat accessor on
23
+ `Settings`.** `Settings` exposes `model`, `llama` and `embed` mirroring the
24
+ YAML sections: `cfg.model.context_length`, `cfg.llama.port`,
25
+ `cfg.model.sampling`. `cfg.model.file` is the `Mimic::Model` for the
26
+ configured path, rebuilt when the path changes. A `cfg.port`-style delegator
27
+ rebuilds the 28-method flat surface this replaced; put the accessor on the
28
+ section that owns the key.
29
+ - **A section object reads through `section` and writes through `writable`.**
30
+ An absent section reads as an empty hash and only a write materialises it, so
31
+ a partial config keeps exactly the sections it carries. Never rebuild a
32
+ section hash from known keys — `~/.llm/config.yaml` carries keys no accessor
33
+ knows about (`model.backend`) and `save` has to preserve them.
34
+ - **`Settings#save` writes `@cfg.slice("model", "llama", "embed")` and nothing
35
+ else.** A hand-added top-level key is dropped on the next save. All writers
36
+ (`llm setup`, `llm path`, `llm config`, `llm embed`) agree on this; don't
37
+ reintroduce a full-hash write for one of them.
38
+ - **All terminal output goes through `Mimic::Ui`.**
39
+ `Ui.green/red/yellow/cyan/gray/bold`, `Ui.banner/panel/table` and
40
+ `Ui::Prompt` (`select`/`ask`/`yes?`) are the whole surface; nothing else names
41
+ `CLI::UI`. The TTY toolkit was swapped out in 2026-08 after five years without
42
+ a release, and the point of the boundary is that the next swap is one file.
43
+ `Ui::Prompt` stays an injected collaborator (`prompt:` kwarg) rather than a
44
+ module call so wizard specs keep a seam that isn't a global stub.
45
+ - **A namespace directory may require its parent back.**
46
+ `llm_config/{settings,model_settings,embed}.rb` each `require_relative
47
+ "../llm_config"` and are required from it in turn. The cycle is harmless
48
+ because every cross-reference (`Embed#model_alias` → `Settings.alias_for`,
49
+ `Settings#model` → `ModelSettings`) resolves at call time. A load-time
50
+ reference across that seam — a superclass, an `include`, a constant in a
51
+ default argument — is what breaks it. Only `mimic`, `mimic/llm_config`,
52
+ `mimic/model` and `agent/hermes` are real entry points; that the
53
+ `llm_config/*` files load standalone is checked by hand after a move, not by
54
+ a spec.
55
+ - **Symbol keys inside the app, string keys only at the YAML/JSON boundary.**
56
+ Config parsed off disk is string-keyed because that is what the format gives
57
+ you; anything constructed and consumed purely in Ruby stays symbol-keyed.
58
+
59
+ ## Ruby traps this port has already fallen into
60
+
61
+ - **`raise SystemExit, "message"` exits 0 and prints nothing.** A String is a
62
+ _message_; status stays 0 and Ruby prints nothing for an uncaught
63
+ `SystemExit`. Five sites shipped this way. Use `abort "msg"` (stderr, exit 1).
64
+ `raise SystemExit, <Integer>` is fine.
65
+ - **Moving a file into a namespace can silently repoint its bare constants.**
66
+ `Mimic::LlmCli::Paths` is a Thor subcommand, so a file moved under `LlmCli`
67
+ resolves bare `Paths::LLM_ROOT` to it and dies with `uninitialized constant` —
68
+ lexical lookup checks the enclosing namespace before `Mimic`. After such a
69
+ move, grep the moved file for bare references to its new siblings' names and
70
+ qualify them (`Mimic::Paths::…`).
71
+ - **A class named for a core Ruby constant shadows it namespace-wide.**
72
+ `Engine::Process` made `Launcher`'s `Process.spawn` resolve to the new class.
73
+ The whole `Engine` tree was affected, not just the defining file. Hence
74
+ `Engine::ServerProcess`.
75
+ - **`reline` and `readline` are not default gems on Ruby 4.0.** cli-ui's
76
+ `prompt.rb` requires both at load and dies with `cannot load such file --
77
+ readline`. `reline` is an explicit gemspec dependency; do not "clean up" that
78
+ seemingly-stdlib entry.
79
+ - **cli-ui's own `Table` renders through `CLI::UI.puts`, which hard-wraps.**
80
+ Both `puts_table` and `capture_table` fold a wide board into fragments at the
81
+ terminal width. `Ui.table` pads columns itself and measures with
82
+ `CLI::UI::ANSI.printing_width` so colour escapes don't count.
83
+ - **Narrow `rescue` clauses swallow less than they look like they do.**
84
+ `rescue Errno::ENOENT` covers one errno; an unreadable file took down all of
85
+ `llm sync` because the real failure was a different errno. Prefer
86
+ `SystemCallError`, and `Psych::Exception` over `Psych::SyntaxError`.
87
+ `Psych.safe_load` needs `permitted_classes: [Symbol, Date, Time]`.
88
+ - **A raise inside a per-client/per-model loop kills the whole run.** Return
89
+ `nil`/`false` from the helper and let the loop continue past one bad entry.
90
+ - **`IO#seek` issues a real `lseek(2)` every call.** A line-for-line seek loop
91
+ can be ~5× slower than it looks — see
92
+ `docs/llm-models-query-performance-issue.md`.
93
+ - **`expand_path` does not resolve symlinks.** `~/hf-models` is a tree of
94
+ per-file symlinks into their `.lmstudio` targets, and anything keyed by model
95
+ path has to resolve through them or it splits into two disagreeing key sets
96
+ (this happened to `~/.llm/model-ctx.json`). Model paths go through
97
+ `LlmConfig.resolve_path`, and `select_model` returns a `realpath`.
98
+ - **A stub only covers the constant the call site actually names.**
99
+ `ik_llama.rb` calls `Base.cleanup_failed(pid)` and `Base.last_lines(tail)`
100
+ literally, not through `self.class`, so `allow(described_class)` — or worse a
101
+ sibling — stubs nothing and the real method runs. That shipped: the ik
102
+ retry-loop specs deleted the live `/tmp/llm/llama-server.pid` on every suite
103
+ run and `llm status` reported `(pid ?)` for a server that was up. Read the
104
+ call site before choosing the stub target; a passing suite does not prove the
105
+ stub bound.
106
+ - **Thor**: `def self.exit_on_failure? = true` must stay, or error paths print a
107
+ deprecation warning and exit 0.
108
+
109
+ ## Scope boundaries
110
+
111
+ - `agent.rb`'s Unsloth-replacement launchers are **claude and codex only**.
112
+ Upstream ships six agents; the other four were cut on purpose. Don't add them
113
+ back. `Agent::Hermes` is not one of them — Hermes is mimic's own agent and
114
+ owns the `~/.hermes` tree (venv, config, logs, state DB).
115
+ - **One file is vendored from upstream unsloth, and only one.**
116
+ `agent/codex_fallback_prompt.md` is a byte-identical copy of
117
+ `unsloth_cli/codex_fallback_prompt.md`, carrying OpenAI's Codex CLI system
118
+ prompt — both Apache-2.0, recorded in `NOTICE`, packaged by the gemspec's
119
+ `lib/**/*` glob. Keep it verbatim: modifying it puts the Apache-2.0 4(b)
120
+ change-notice obligation on us and makes upstream diffs meaningless. Nothing
121
+ else is vendored — `Agent::Claude` / `Agent::Codex` reimplement unsloth's
122
+ launch recipe, and `../unsloth/` is a reference checkout, not a runtime
123
+ dependency. Reviewing upstream for changes worth reimplementing is a periodic
124
+ judgement pass, run from this machine's `/sync-unsloth-cc-codex` against an untracked
125
+ `UPSTREAM-REVIEW.md` ledger.
126
+ - **`Engine::LlamaEmbed` is selected by role, never by config, so it must stay
127
+ out of `EngineCli::Registry::ENGINES`.** `Registry.for(settings)` dispatches
128
+ on `cfg.llama.engine` and `Registry.names` drives the setup wizard's engine
129
+ picker (`llm_cli/wizard/setup.rb:70`, pinned by
130
+ `spec/llm_cli/wizard/setup_spec.rb:43`); an entry there would offer the
131
+ embedding server as a chat engine. The eight chat-only private methods it
132
+ inherits and never calls were the accepted price of `Base` already being
133
+ abstract, not an oversight to tidy.
134
+ - **`llm setup` is the only setup wizard.** `mimic` had a second one that
135
+ duplicated its six engine/model steps; it was never a command, only a
136
+ no-config fallback, and it went in 2026-08. `mimic` now aborts with "run `llm
137
+ setup` first". The one thing it did that `llm setup` does not is
138
+ `Agent::Hermes.install`, which survives behind `mimic install-hermes`. Don't
139
+ reintroduce a `mimic setup`.
140
+ - **`mimic` owns no config of its own.** It reads `~/.llm/config.yaml` and
141
+ writes other tools' files. Resist adding a settings layer — one was deleted in
142
+ 2026-07 for being dead weight, and the `Mimic::Config` shim that outlived it
143
+ went in 2026-08. Read config through `LlmConfig`; a path another tool owns
144
+ belongs on that tool's own module.