| name | file-issue |
| description | File a mimi bug report or feature request that matches the repo's issue forms: duplicate check first, every required field filled with real diagnostics, correct labels. Use when asked to open, file, or draft a GitHub issue for mimi. Not for pull requests. |
Filing an issue in mimi
Blank issues are disabled (.github/ISSUE_TEMPLATE/config.yml) — everything
goes through a form, and an agent-filed issue must contain the same fields the
form enforces. gh issue create bypasses form validation, so you are the
validator.
Always, before filing
- Search for duplicates — the forms make humans attest to this, so do it
for real:
gh issue list --search "<keywords>" --state all, plus
discussions for feature ideas. Found one? Comment there instead of filing.
- Route non-issues away. Questions, config help, and "here's my setup"
belong in Discussions — the
forms link there deliberately. Filing an issue for these is wrong even if
the user asked for an issue: say so and offer the right venue.
- Check whether it's macOS telling the truth. Space switching and
window-to-space moves ride private SkyLight APIs and synthetic dock swipes;
a missing Accessibility grant looks exactly like a broken action. Confirm
the permission state before calling it a bug —
docs/TROUBLESHOOTING.md and
docs/ARCHITECTURE.md (Permissions) cover which paths need which grant.
Bug report (--label bug)
Mirror bug_report.yml's fields as markdown sections, all of them:
- Mimi version — real output of
mimi version, never guessed.
- macOS version — real output of
sw_vers, quoted as e.g. macOS 15.3.1.
Version matters more here than in most repos: the private APIs shift between
releases.
- What happened / What did you expect — observed vs expected, concrete.
- Steps to reproduce — numbered, minimal, starting from a known state
(
mimi daemon start, or the exact mimi action … invocation).
- Config (relevant sections) — only the TOML sections involved, fenced as
toml. Strip anything personal: hook commands run arbitrary shell, so
scrub paths, hostnames, and command bodies that aren't load-bearing.
- Screenshots / recordings and Additional context when they help.
For daemon and hook bugs, the useful extras are: whether the daemon was
running (the CLI silently falls back to direct execution when the socket at
settings.socket_file is unavailable — a behavior difference that is itself
often the bug), which hook fired or didn't, and daemon logs at debug level.
Feature request (--label enhancement)
Mirror feature_request.yml:
- Problem or use case — the need, not the mechanism. This is the section
maintainers judge; write it first and best.
- Proposed solution — how it would work, with a concrete TOML snippet if
it adds config, or the exact command line if it adds CLI surface.
- Alternatives considered — including whether an existing hook plus a
shell command already gets there. mimi's hook system is the escape hatch;
a request that shell already solves usually loses.
- Screenshots / mockups, optional.
- Contribution — state plainly whether a PR will follow.
Filing
Draft the body, show it to the user before creating (an issue posts publicly
under their account), then:
gh issue create --title "<concise, user-facing summary>" --label bug --body-file <draft>
Title style matches the tracker: plain sentence, no conventional-commit
prefix, no trailing period.
The forms apply bug / enhancement automatically; gh does not, so pass it
yourself. gh label list is the authority on what else exists — today that's
documentation, question, duplicate, invalid, good first issue,
help wanted, plus the triage-state labels in docs/agents/triage-labels.md.
Don't invent new ones while filing.
