--- name: MulmoTerminal Bug Report slug: mulmoterminal-bug-report category: Quality description: MulmoTerminal Bug Report hears a broken or weird MulmoTerminal symptom, checks config, schema, version, and existing issues, then files a GitHub issue only if the problem remains unexplained. Use it when MulmoTerminal is not working as expected or you need help reporting a bug. github: "https://github.com/receptron/mulmoterminal/tree/main/server/skills/mulmoterminal-bug-report" language: TypeScript stars: 202 forks: 31 install: "npx degit https://github.com/receptron/mulmoterminal/tree/main/server/skills/mulmoterminal-bug-report ~/.claude/skills/mulmoterminal-bug-report" installs_to: ~/.claude/skills/mulmoterminal-bug-report source_path: server/skills/mulmoterminal-bug-report/SKILL.md collection_size: 12 category_size: 1662 collection_url: "https://dirskills.com/collections/receptron/mulmoterminal" added: 2026-09-05T05:30:13.649Z last_synced: 2026-09-05T05:30:13.649Z canonical_url: "https://dirskills.com/skills/mulmoterminal-bug-report" --- # MulmoTerminal Bug Report MulmoTerminal Bug Report hears a broken or weird MulmoTerminal symptom, checks config, schema, version, and existing issues, then files a GitHub issue only if the problem remains unexplained. Use it when MulmoTerminal is not working as expected or you need help reporting a bug. **Install:** ```bash npx degit https://github.com/receptron/mulmoterminal/tree/main/server/skills/mulmoterminal-bug-report ~/.claude/skills/mulmoterminal-bug-report ``` ## README # MulmoTerminal — is it a bug? **The goal is that the user ends up unblocked, not that an issue gets filed.** An issue is what's left after the other three steps fail to explain the behaviour. Work the steps in order. Stop the moment the user is unblocked. ## Rules that hold in every step - **Never assert "that's by design" from memory.** Say it only with a reason attached: a config key, an implementation file, a guide page. `faq.md` is an index of where to look — it deliberately contains no values. - **Read the real thing.** Current and default values come from the user's actual config file, the schema in the source, or the running server — never from this file, and never from recollection. - **"I don't know" is an allowed answer.** If a step cannot decide, say so and go to the next one. Never close the conversation by guessing. - **Nothing leaves the machine before the user has seen it in full** and said yes. - Reply in the language the user writes in. ## Step 1 — Hear the symptom (collect nothing yet) Ask with `AskUserQuestion`, options first — a user who is already frustrated should be picking, not composing. Up to 4 questions per call; two calls cover this comfortably. - **What kind** — display looks wrong / input doesn't work / a session died or won't connect / won't start at all / phone features / something else - **Where** — a grid cell / the zoomed view / the single view / the file browser / settings / phone - **Which agent** — claude / codex / shell / a launcher cell / a command cell - **How often** — every time / sometimes / once - **Since when** — after an update / it always did this / not sure Then, in prose: **what did you expect, and what happened instead?** Those two sentences are what the next step is judged against, so get them before touching anything else. ## Step 2 — Is it configuration, or by design? (this is the actual job) 1. Read `faq.md` (next to this file) and find the entry closest to the symptom. 2. Follow its pointers to the **real values**: - global config: `~/.mulmoterminal/config.json` - directory config: `/.mulmoterminal.json` - the running server: `curl -s http://localhost:34567/api/config` (34567 is the default port; if the user changed it, it's the port in their browser's address bar). `/api/update-status`, `/api/sessions`, `/api/git-status?cwd=` and `/api/dir-config?cwd=` answer too. - the source files named by the entry, when the question is about accepted values or behaviour 3. If that explains the gap between expected and actual, **say why, show the fix, and stop.** - If the fix is a `.mulmoterminal.json`, hand off to `/mulmoterminal-config` instead of dictating JSON — it knows the schema and validates. 4. If nothing explains it, or the explanation is a guess, go to Step 3. Do not stretch the FAQ to cover a symptom it doesn't cover. Solved here? Offer to post it as an **FAQ issue** (see the last section) — but only if someone else would plausibly hit the same wall. ## Step 3 — Is it already known? ```bash gh issue list --repo receptron/mulmoterminal --state all --limit 20 --search "" ``` No `gh`? Hand over the search URL instead: `https://github.com/receptron/mulmoterminal/issues?q=` - **Closed and fixed** → compare the user's version against the release that fixed it. If they're simply behind, tell them to update and stop. (Version: the package's `package.json`; `/api/update-status` says whether a newer one exists.) - **Open** → do not open a second one. Offer to add this user's environment and repro steps as a comment — a second reproduction is worth more than a duplicate. - **Nothing found** → Step 4. ## Step 4 — File it Only now collect details. ```bash node -p "require('/package.json').version" # or the version in the web header node -v && uname -sm && echo "$SHELL" tmux -V; gh --version | head -1; claude --version; codex --version # each may be absent curl -s http://localhost:34567/api/update-status curl -s http://localhost:34567/api/sessions # summarize: cell count, agents, live vs tmux-only curl -s "http://localhost:34567/api/git-status?cwd=" cat ~/.mulmoterminal/config.json # mask before quoting cat /.mulmoterminal.json # mask before quoting ``` Ask the user for what the host cannot see: the browser and its version, any red errors in the browser console, and a screenshot if the symptom is visual. **Masking, before anything is written into a report:** - Anything key-shaped — `*_KEY`, `*_TOKEN`, `Authorization`, provider credentials — is reported as the key name with `***` for the value. Never the value, not even partially. - Shorten the home directory to `~` in every path. - A terminal screenshot can carry prompt text and internal paths — say so before it's attached. **Report body:** ```markdown ## What happened ## What I expected ## Steps to reproduce 1. ## Environment - mulmoterminal / Node / OS / browser - tmux / gh / claude / codex - how it was started (npx, local dev) ## Attachments ``` Show the whole thing, get an explicit yes, then: ```bash gh issue create --repo receptron/mulmoterminal --title "" --body-file <file> ``` No `gh`? Print the markdown for copy-paste plus `https://github.com/receptron/mulmoterminal/issues/new`. ## FAQ issues (when Step 2 resolved it) A question that took a human to answer is a signal about the product, so it's worth recording — but only with the user's agreement, and never as an authoritative answer. - Title: the question as the user asked it. Body: what was asked, what the answer turned out to be, and **where it was checked** (config key / file). - Open the body with a line saying the answer came from this skill and is **awaiting maintainer review** — the answer here is a draft, not documentation. - If an FAQ issue for the same question already exists, comment there instead of opening another. - Never edit `faq.md` yourself. A maintainer reviews the issue and folds it into the repo; this skill only posts.