xonecas.io
64875
Mc

mini-coder / commit 8a3e281

docs: add tmux guide to mini-coder skill

Add a 'Using tmux with mc' section covering setup, paste detection
behavior, input/output patterns, special keys, and a full example.
Restore 'Tips for helping users' heading.

xonecas2026-03-20 8a3e2815f3983a8dff1c9999ebf42c1ffdf435a0 parent d8b4903

2 files changed

.agents/skills/mini-coder/SKILL.md+80−0
@@ -114,6 +114,86 @@ For complex, multi-part tasks you can use `mc` as a subagent coordinator.
114114 - Trivial lookups or single-file reads — do them directly.
115115 - Tasks requiring continuous back-and-forth with the user — handle interactively.
116116
117+## Using tmux with mc
118+
119+When testing `mc` interactively from an outer agent or script, use `tmux` to drive the session. This avoids the limitations of non-interactive shell invocations.
120+
121+### Setup
122+
123+```sh
124+tmux new-session -d -s test -x 200 -y 50
125+tmux send-keys -t test 'bun run dev' Enter # or 'mc'
126+sleep 3 # wait for banner
127+```
128+
129+### Sending input
130+
131+Use `-l` (literal) to avoid key-name interpretation, then send `Enter` separately:
132+
133+```sh
134+tmux send-keys -t test -l "What files are in src/"
135+tmux send-keys -t test Enter
136+sleep 10
137+tmux capture-pane -t test -p -S -30 # read last 30 lines
138+```
139+
140+### Paste detection
141+
142+`mc` uses bracketed paste mode. When `tmux send-keys` delivers text rapidly (even with `-l`), the terminal may wrap it in paste brackets. This causes `mc` to show a `[pasted: "…"]` label instead of echoing the typed text. **This is expected behavior** — real users typing character-by-character won't trigger it.
143+
144+To work around it in automation:
145+
146+- **Short prompts**: use `send-keys -l "text"` + `send-keys Enter` — paste label is cosmetic, submission still works.
147+- **Slash commands**: same pattern — `/model zen/claude-haiku-4-5` + `Enter`.
148+- **Multi-line input**: not supported in the prompt; send one logical prompt per submission.
149+
150+### Reading output
151+
152+```sh
153+tmux capture-pane -t test -p -S -50 # last 50 lines
154+tmux capture-pane -t test -p -S -50 -E -1 # specific range
155+```
156+
157+Capture after a generous `sleep` — tool calls and streaming take time.
158+
159+### Sending special keys
160+
161+```sh
162+tmux send-keys -t test Escape # interrupt response (ESC)
163+tmux send-keys -t test C-d # graceful exit (Ctrl+D)
164+tmux send-keys -t test C-c # force exit (Ctrl+C)
165+```
166+
167+### Cleanup
168+
169+```sh
170+tmux send-keys -t test C-d
171+sleep 1
172+tmux kill-session -t test
173+```
174+
175+### Full example: test a model switch + prompt
176+
177+```sh
178+tmux new-session -d -s test -x 200 -y 50
179+tmux send-keys -t test 'mc' Enter
180+sleep 3
181+
182+tmux send-keys -t test -l "/model zen/gemini-3-flash"
183+tmux send-keys -t test Enter
184+sleep 2
185+
186+tmux send-keys -t test -l "List the files in the current directory"
187+tmux send-keys -t test Enter
188+sleep 15
189+
190+tmux capture-pane -t test -p -S -30 # review output
191+
192+tmux send-keys -t test C-d
193+sleep 1
194+tmux kill-session -t test
195+```
196+
117197 ## Tips for helping users
118198
119199 - Prefer exact commands the user can paste.
AUDIT-REPORT.md+103−0
@@ -0,0 +1,103 @@
1+# Audit Report — mini-coder v0.2.0
2+
3+**Date:** 2026-03-20
4+**Auditor:** Claude Code (automated audit)
5+
6+---
7+
8+## Summary
9+
10+### How I tested
11+
12+1. **Code review**: Read every module (15,116 lines across ~80 source files). Verified tests (290 pass), lint, types, formatting, knip, and jscpd all pass clean.
13+2. **One-shot tests** across 5 SDK paths: `zen/claude-haiku-4-5`, `zen/gemini-3-flash`, `zen/gpt-5.4-nano`, `zen/minimax-m2.5`, and `anthropic/claude-haiku-4-5` (OAuth). Exercised simple prompts and tool-calling (shell reads).
14+3. **Interactive tmux sessions**: Multi-turn conversations with model switching, `/help`, `/undo`, `/new`, `!shell`, `/model`, skill listing — tested across all 5 provider paths in the same session.
15+
16+### Overall
17+
18+The codebase is **well-architected, cleanly separated, and functional across all tested providers**. The core idea is faithfully implemented. The handful of issues found are mostly minor refinements and one moderate architectural concern.
19+
20+---
21+
22+## Code & Architecture
23+
24+### Correctness issues
25+
26+1. **MCP client version hardcoded to `0.1.0`** (`src/mcp/client.ts:30`). Package is at `0.2.0`. Should derive from `__PACKAGE_VERSION__` or at least stay in sync.
27+
28+2. **Context pruning fires spuriously on clean conversations** — Anthropic OAuth path showed `context pruned –0 messages –0.4 KB` on a short conversation. The pruned event fires because `postPruneTotalBytes < prePruneTotalBytes` even though no messages were removed — the byte delta comes from provider-option stripping in sanitisation, not actual pruning. This is cosmetically confusing but functionally harmless. The `pruned` flag in `prepareTurnMessages` should compare message counts only …
29+
30+3. **Error log writes are not append-mode** — `logError()` in `error-log.ts` does `writer.write(…)` but each call overwrites context since there's no separator between entries. Two rapid errors will concatenate without a newline boundary between them. The api-log correctly uses `---\n` separators; error-log should do the same.
31+
32+### KISS/DRY/YAGNI
33+
34+4. **Three near-identical `truncate` functions** — `truncate()` in `tool-render.ts`, `truncateOneLine()` in `tool-result-renderers.ts`, and `truncatePlainText()` in `status-bar.ts` all implement `s.length > max ? s.slice(0, max-1) + "…" : s`. This is tracked in KNOWN_ISSUES as "consolidate truncation helpers" but worth emphasizing as it's the lowest-hanging DRY violation.
35+
36+5. **Dual frontmatter parsers** — `parseSkillFrontmatter` (skills.ts, line-by-line from fd) and `parseFrontmatter` (frontmatter.ts, regex-based from string) both parse the same `---\nkey: value\n---` format with identical key-value extraction logic. Also tracked in KNOWN_ISSUES. The skills parser is more efficient (reads only the first 2KB) — consolidation should keep that optimization.
37+
38+6. **`isOpenAIReasoningModelFamily` is overly broad** — `modelId.startsWith("gpt-5")` classifies all GPT-5.x models (including nano) as reasoning-capable. This is currently gated by `supportsThinking()` from models.dev data, so no runtime bug, but it means thinking provider options would be attempted on nano models if models.dev data is stale or missing. The function name implies it checks for reasoning capability, but it's really checking for the responses API endpoint family.
39+
40+### Alignment with core idea
41+
42+7. **"Conversation summary on max context"** — The core idea states "Stops with a conversation summary if max context is reached." Currently tracked in KNOWN_ISSUES as a feature gap. The current behavior is an error + suggestion to `/new`. This is the biggest feature gap vs. the specification.
43+
44+8. **`maxOutputTokens` hardcoded at 16384** (`turn-request.ts:71`) — The core idea says "Derive maxOutputTokens from model info." Tracked in KNOWN_ISSUES. Some models (e.g. Gemini 3 Flash, GPT-5.4) support much higher output limits.
45+
46+---
47+
48+## UI/UX Alignment
49+
50+### Across all providers
51+
52+| Aspect | Expected (core idea) | Actual | Verdict |
53+| ------------------------ | ------------------------------------------- | ---------------------------------------------------------------- | ------- |
54+| Banner at start | Model, cwd, found configs, skills | ✓ Shows all: model, cwd, AGENTS.md, skill count | ✅ |
55+| Status bar | Model, session, git branch, tokens, context | ✓ All present, context % colored at thresholds | ✅ |
56+| Spinner during wait | Colored animation with labels | ✓ Braille spinner on stderr with tool/thinking labels | ✅ |
57+| Shell tool rendering | Command + output | ✓ Smart glyphs (read/write/search), exit code, head/tail preview | ✅ |
58+| Skill tool rendering | Compact metadata | ✓ Name, source, description — compact and readable | ✅ |
59+| `/help` | Commands overview | ✓ Comprehensive, grouped, includes skills | ✅ |
60+| `/undo` | Remove last turn | ✓ Works correctly, removes from DB + memory | ✅ |
61+| `/new` | Fresh session, clean display | ✓ Clears screen, reprints banner | ✅ |
62+| `/model` | Switch with autocomplete | ✓ Switches, persists, updates status bar | ✅ |
63+| `!cmd` shell integration | Run + keep in context | ✓ Renders output, adds to history | ✅ |
64+| ESC to interrupt | Partial response preserved | Verified in code — uses AbortController + stub append | ✅ |
65+| 16 ANSI colors only | Inherits terminal theme | ✓ Uses yoctocolors, all glyphs from 16-color palette | ✅ |
66+
67+### Provider-specific findings
68+
69+| Provider | One-shot | Interactive | Tool calling | Notes |
70+| ------------------------------------ | -------- | ----------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
71+| `zen/claude-haiku-4-5` | ✅ | ✅ | ✅ | Clean, fast |
72+| `zen/gemini-3-flash` | ✅ | ✅ | ✅ | Clean, fast |
73+| `zen/gpt-5.4-nano` | ✅ | ✅ | ✅ | Clean. Correctly uses responses endpoint |
74+| `zen/minimax-m2.5` | ✅ | ✅ | ✅ | **Blank lines in one-shot output** (known issue). Interactive mode looks fine. Reasoning blocks render correctly. |
75+| `anthropic/claude-haiku-4-5` (OAuth) | ✅ | ✅ | ✅ | OAuth identity injection works. Spurious pruning event (item 2 above). |
76+
77+### UI observations
78+
79+- **Paste detection in tmux**: When `tmux send-keys` sends text rapidly, bracketed paste mode activates and shows `[pasted: "..."]` label instead of the typed text. This is correct behavior — it's how the terminal reports pasted input. Using `-l` flag for literal keys avoids this. Real users typing normally won't see this.
80+- **Output hierarchy**: The `›` (user) → `$` (shell) / `?` (search) / `←` (read) / `✎` (write) → `◆` (assistant) visual hierarchy is clear and consistent across all providers.
81+- **Token tracking**: Cumulative `tok in/out` and `ctx` with percentage are accurate and update correctly after each turn and model switch.
82+
83+---
84+
85+## Recommendations
86+
87+### Immediate bugs
88+
89+1. **Fix spurious "context pruned" event on Anthropic OAuth** — Compare only message counts (not bytes) when determining if pruning occurred, or set a minimum byte threshold (e.g. 1KB) to suppress noise.
90+2. **Error log entry separation** — Add `\n---\n` separators in `logError()` to match api-log format.
91+3. **MCP client version** — Use `__PACKAGE_VERSION__` or synchronize with package.json.
92+
93+### Code changes
94+
95+4. **Consolidate truncation helpers** — Create `src/cli/truncate.ts` with a single `truncate(s, max)` function. (KNOWN_ISSUES item)
96+5. **Consolidate frontmatter parsers** — Unify `parseSkillFrontmatter` and `parseFrontmatter` into one module that supports both string and fd-based input. (KNOWN_ISSUES item)
97+6. **Derive `maxOutputTokens` from model info** — Use `resolveModelInfo()` to get model-specific limits. Fall back to 16384. (KNOWN_ISSUES item)
98+
99+### Polish items
100+
101+7. **Conversation summary on max context** — The most impactful feature gap. When context is exhausted, produce a summary of the conversation so far before starting fresh. (KNOWN_ISSUES item)
102+8. **MiniMax blank lines in one-shot** — The empty text deltas from MiniMax produce visible blank lines before the response. Stripping leading whitespace from the final one-shot output, or filtering empty text-delta events, would fix this.
103+9. **Status bar: `showReasoning`** — The status bar signature includes `showReasoning` but it's not rendered in the status line (only in the banner). Either add it to the status bar or remove it from the signature to avoid unnecessary re-renders. (Partially tracked in KNOWN_ISSUES as "drop showReasoning from status bar")