{"id":49591317,"url":"https://github.com/mcamner/macos-scripts","last_synced_at":"2026-06-02T19:00:25.486Z","repository":{"id":346246990,"uuid":"1189040864","full_name":"MCamner/macos-scripts","owner":"MCamner","description":"A modular CLI for structured terminal workflows, automation, and system tools on macOS.","archived":false,"fork":false,"pushed_at":"2026-06-02T01:42:02.000Z","size":3936,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T03:21:39.349Z","etag":null,"topics":["automation","cli","macos","scripts","shell","terminal","workflows","zsh"],"latest_commit_sha":null,"homepage":"https://mcamner.github.io/macos-scripts/case.html","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MCamner.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T22:58:19.000Z","updated_at":"2026-06-02T01:42:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MCamner/macos-scripts","commit_stats":null,"previous_names":["mcamner/macos-scripts"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/MCamner/macos-scripts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MCamner%2Fmacos-scripts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MCamner%2Fmacos-scripts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MCamner%2Fmacos-scripts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MCamner%2Fmacos-scripts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MCamner","download_url":"https://codeload.github.com/MCamner/macos-scripts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MCamner%2Fmacos-scripts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33833277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli","macos","scripts","shell","terminal","workflows","zsh"],"created_at":"2026-05-04T01:01:34.395Z","updated_at":"2026-06-02T19:00:25.478Z","avatar_url":"https://github.com/MCamner.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# macos-scripts ⚡\n\n![macOS](https://img.shields.io/badge/platform-macOS-black)\n![Shell](https://img.shields.io/badge/shell-zsh%20%2B%20bash-1f6feb)\n![Version](https://img.shields.io/badge/version-0.5.0-blue)\n![License](https://img.shields.io/badge/license-MIT-2ea44f)\n![Status](https://img.shields.io/badge/status-active-success)\n\nTurn scattered shell commands into structured workflows.\n\n👉 **View case study:**\n[mcamner.github.io/macos-scripts/case.html](https://mcamner.github.io/macos-scripts/case.html)\n\nStop memorizing commands. Start running workflows.\n\n---\n\n## Proof\n\n- `install.sh` supports `--dry-run`, `--uninstall`, and `--yes` (non-interactive)\n- `release.sh` validates VERSION, README badge, and CHANGELOG before every release\n- `mqlaunch doctor` supports `--json` output — machine-readable health report\n- `mqlaunch selftest` runs launcher smoke checks and shell syntax lint\n- `mqlaunch release-check` gates every release on a `repo-signal` publish-readiness score\n- HAL bridge supports read-only audit, release brief, repo status, and CI status\n- All `.sh` files pass `bash -n` syntax check — verified by CI and `scripts/install-smoke.sh`\n- GitHub Pages has smoke-test coverage via CI\n\n---\n\n## Quick start\n\n### Requirements\n\nThis project is built for macOS with `zsh`/`bash`. The doctor command checks\nthe local tools used by the workflows, including `git`, `brew`, `node`,\n`python`, and `jq`.\n\n### Option 1 — Install (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/MCamner/macos-scripts/main/install.sh | bash\n```\n\nPreview install changes without modifying your system:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/MCamner/macos-scripts/main/install.sh | bash -- --dry-run\n```\n\n### Option 2 — Clone\n\n```bash\ngit clone https://github.com/MCamner/macos-scripts.git\ncd macos-scripts\n./install.sh\n```\n\nUninstall later with:\n\n```bash\n./install.sh --uninstall\n```\n\n---\n\n## ⚡ First run\n\n```bash\nmqlaunch doctor\n```\n\nThis will:\n\n* verify your environment\n* check required dependencies\n* validate your setup\n* highlight issues with clear fixes\n\n---\n\n## 🚦 Then explore\n\n```bash\nmqlaunch\n```\n\n* browse workflows via the interactive menu\n* or run commands directly (`perf`, `system`, `dev`, `tools`)\n\n## Usage\n\nUse `mqlaunch` when you want a menu, and direct commands when you already know\nthe workflow:\n\n```bash\nmqlaunch                         # browse menus\nmqlaunch palette                 # fuzzy command search\nmqlaunch system check            # system health report\nmqlaunch workflows boot          # project boot workflow\nmqlaunch workflows validate      # workflow command-surface health check\nmqlaunch workflows save          # save workspace snapshot\nmqlaunch release-check           # release readiness gate\nmqlaunch repos status            # MQ ecosystem repo status\n```\n\n---\n\n## ⚡ One command instead of many\n\nInstead of:\n\n```bash\ntop\ndf -h\nps aux | sort -nrk 3 | head\n./tools/scripts/system-check.sh\n```\n\nRun:\n\n```bash\nmqlaunch perf\n```\n\n## Examples\n\n```bash\nmqlaunch hal brief               # compact repo status brief\nmqlaunch hal audit               # publish quality + README score\nmqlaunch review                  # delegate diff review to mq-agent/mq-mcp\nmqlaunch fix \"explain this shell error\"\nmqlaunch srm ask \"what is indexed in this repo memory?\"\n```\n\n---\n\n## 🎯 What this solves\n\nMost environments don't lack tools — they lack structure.\n\nThis project turns:\n\n\u003e useful chaos → usable system\n\n---\n\n## 🧠 Core idea\n\nOne command → structured workflows → repeatable execution\n\n* single entrypoint: `mqlaunch`\n* organized workflows (Dev, System, Performance, Git, Release, Tools)\n* works as interactive menu and direct CLI\n* built-in AI for questions, code generation, and error fixes\n\n---\n\n## 🧰 Common commands\n\n```bash\nmqlaunch                         # interactive menu\nmqlaunch perf                    # performance overview\nmqlaunch system check            # system health\nmqlaunch dev                     # dev workflows\nmqlaunch git                     # git menu\nmqlaunch release                 # release menu\nmqlaunch ask \"your question\"     # AI repo assistant\nmqlaunch srm ask \"your question\" # Semantic Repository Memory assistant\nmqlaunch fix \"error or task\"     # AI generates copy-paste shell commands\nmqlaunch atlas                   # AI REPL session\nmqlaunch review                  # review current diff via mq-agent -\u003e mq-mcp\nmqlaunch risk-review             # risk review via mq-agent -\u003e mq-mcp\nmqlaunch architecture            # show mq-mcp architecture memory\nmqlaunch repo-health             # repo-signal + mq-mcp contract health\nmqlaunch mcp-status              # mq-mcp status and tool count\nmqlaunch hal                     # open HAL menu\nmqlaunch hal \"your request\"      # local Ollama-powered safe command router\nmqlaunch hal repos               # list HAL-known repos\nmqlaunch hal raw \"your request\"  # show parsed JSON intent\nmqlaunch hal doctor              # summarize mqlaunch doctor --json with local HAL\nmqlaunch hal fix-doctor          # create safe fix plan from HAL Doctor Summary\nmqlaunch hal session             # show local HAL session memory\nmqlaunch hal last                # show latest HAL memory item\nmqlaunch hal remember \"note\"     # save a local HAL note\nmqlaunch hal timeline            # show HAL session memory as compact timeline\nmqlaunch hal brief               # compact repo status brief\nmqlaunch hal release-brief       # release readiness brief\nmqlaunch hal audit               # publish quality + README score via repo-signal\nmqlaunch hal repo-status         # read-only git repo status\nmqlaunch hal ci                  # GitHub Actions status\nmqlaunch doctor                  # environment check\nmqlaunch doctor --json           # machine-readable JSON health report\nmqlaunch workflows validate      # workflow files, docs and routing check\nmqlaunch selftest                # smoke tests + shell lint\nmqlaunch release-check           # release readiness check\nmqlaunch demo                    # guided demo\n```\n\n👉 **Full command reference:** [docs/COMMANDS.md](docs/COMMANDS.md)\n\nHAL command surface: [docs/hal-command-surface.md](docs/hal-command-surface.md)\n\nHAL gallery: [docs/hal-gallery.md](docs/hal-gallery.md)\n\nHAL overview page: [docs/hal.html](docs/hal.html)\n\nHAL menu screenshot: [docs/screenshots/hal-menu.png](docs/screenshots/hal-menu.png)\n\n## 📚 Documentation map\n\n- [Command reference](docs/COMMANDS.md) — full `mqlaunch` command surface\n- [Terminal guide](terminal/README.md) — launchers, menus, themes, and bridges\n- [Tools guide](tools/README.md) — helper scripts and utility workflows\n- [Automation guide](automation/README.md) — login, shortcuts, and workflows\n- [System guide](system/README.md) — macOS tweaks, monitoring, and performance\n- [Skills](SKILLS.md) — local maintenance skills for this repo\n- [Roadmap](ROADMAP.md) — current design boundary and next priorities\n\n---\n\n## 🤖 AI assistant\n\nAsk questions about the repo directly in the terminal:\n\n```bash\nmqlaunch ask \"how does command routing work?\"\nmqlaunch ask \"what does doctor.sh check?\"\n```\n\nThe repo assistant uses Semantic Repository Memory by default:\n\n```bash\nMQ_REPO_VECTOR_STORE_ID=vs_your_repo_store_id\n```\n\nQuery a specific Semantic Repository Memory store with the Responses API:\n\n```bash\nmqlaunch srm inspect\nmqlaunch srm ask \"what repo is indexed here?\"\nSRM_VECTOR_STORE_ID=vs_your_semantic_memory_store_id mqlaunch srm search \"vector store upload flow\"\n```\n\nStart an interactive session with Atlas — a senior systems engineer\nembedded in mqlaunch:\n\n```bash\nmqlaunch atlas\n```\n\n```text\natlas\u003e why is my push being blocked?\natlas\u003e explain the release flow\natlas\u003e exit\n```\n\nAtlas answers inline without opening a browser.\n\n---\n\n## 🔧 Fix and generate code\n\nGet copy-paste ready shell commands for errors and tasks:\n\n```bash\nmqlaunch fix \"ERROR: CHANGELOG does not contain version 0.1.9\"\nmqlaunch fix \"write a function that checks if a port is in use\"\nmqlaunch fix \"add option 13 'View stash' to the git menu\"\n```\n\nOutput is always runnable — `cat` heredocs, `sed`, `mkdir` — no theory:\n\n```bash\n# Add changelog section for 0.1.9\ncat \u003e\u003e CHANGELOG.md \u003c\u003c 'EOF'\n## [0.1.9] - 2026-05-07\n### Changed\n* ...\nEOF\n```\n\nCopy, paste, run. Uses repo context from the vector store.\n\n---\n\n## 🚢 Release workflow\n\nAuto Release handles the full release cycle in one flow:\n\n```bash\nmqlaunch release\n# → select option 11: Auto Release\n```\n\nSteps:\n\n1. Auto-generate changelog section from commits since last tag\n2. Dry run — validates VERSION, README badge, and CHANGELOG\n3. Live release — bumps version, tags, updates files\n4. Git push + push tags\n5. Create GitHub release\n\nRun the release check before every push:\n\n```bash\nmqlaunch release-check\n```\n\nThe release check includes a `repo-signal` publish-readiness gate. Override the threshold with:\n\n```bash\nMQ_REPO_SIGNAL_FAIL_UNDER=14 mqlaunch release-check\n```\n\n---\n\n## 🏷️ Nickname\n\nSet a name that appears in every menu header:\n\n```bash\nmqlaunch nickname-set \"your name\"\n```\n\nStored in `~/.mqlaunch_nickname`.\n\n---\n\n## 🔎 Performance scan\n\n```bash\nmq scan\n```\n\nRanks CPU and memory offenders, highlights repeat offenders, and gives\npractical recommendations for what to close or restart.\n\n---\n\n## 🩺 Health check\n\n```bash\nmqlaunch doctor\nmqlaunch workflows validate\n```\n\n* checks required tools (git, brew, node, python, jq)\n* validates repo state (branch, dirty tree, required files)\n* evaluates workflow readiness (Git, Release, Dev, System)\n* highlights issues and gives actionable recommendations\n\n---\n\n## 🧪 Selftest\n\n```bash\nmqlaunch selftest\n```\n\nRuns launcher smoke checks, v1 compatibility checks, and shell lint for\nsupported bash/sh scripts.\n\n---\n\n## 🎬 Demo\n\n```bash\nmqlaunch demo\n```\n\n---\n\n## Screenshots\n\n### Release Menu\n\n![Release menu screenshot](docs/screenshots/readme-release-menu.svg)\n\n### Performance Hub\n\n![Performance hub screenshot](docs/screenshots/readme-performance-hub.svg)\n\n### Main Menu\n\n![Main menu screenshot](docs/screenshots/readme-main-menu.svg)\n\n---\n\n## 🧱 Project structure\n\n```text\nmacos-scripts/\n├── bin/               # CLI entrypoints\n├── terminal/          # menus, launchers, themes\n├── tools/             # scripts and utilities\n├── system/            # macOS helpers\n├── automation/        # workflows\n├── ai-prompts/        # AI assistant prompts\n├── ui/                # terminal UI\n├── docs/              # screenshots and documentation\n└── backups/           # workspace snapshots\n```\n\n---\n\n## ⚖️ Design principles\n\n* keep it simple\n* structure \u003e more tools\n* optimize for real usage\n* make workflows repeatable\n* reduce cognitive load\n\n---\n\n## 🎬 Case Study\n\nSee how macos-scripts is designed as a structured CLI system:\n\n👉 [mcamner.github.io/macos-scripts/case.html](https://mcamner.github.io/macos-scripts/case.html)\n\n---\n\n## 📈 Real use case\n\nInstead of remembering 5–10 system commands during troubleshooting:\n\n```bash\nmqlaunch system check\n```\n\n→ full system overview in one step\n\n---\n\n## Roadmap\n\nCurrent focus is documented in [ROADMAP.md](ROADMAP.md). The main boundary is:\n\n```text\nmqlaunch shows menu → delegates → mq-agent orchestrates → mq-mcp executes\n```\n\nNear-term priorities:\n\n* release gate integration\n* plugin-style extensions\n* remote execution support\n* improved onboarding\n\n---\n\n## Contributing\n\nPRs and issues are welcome.\n\nGood first contributions:\n\n* add or improve a workflow under `automation/`, `tools/`, or `system/`\n* improve command docs in [docs/COMMANDS.md](docs/COMMANDS.md)\n* add smoke coverage under `tests/`\n* polish terminal menu labels, spacing, or discoverability\n\nBefore opening a PR, run:\n\n```bash\nmqlaunch selftest\nmqlaunch release-check\n```\n\n---\n\n## 🔒 Security\n\nCore scripts run locally on your machine.\n\nAI-assisted commands (`ask`, `fix`, `atlas`, `srm`) may send prompts, selected\nrepository context, or error text to the configured AI provider. Do not use\nAI commands with secrets, private credentials, or sensitive files unless you\nunderstand what is being sent.\n\nNever commit API keys, tokens, or credentials. Use environment variables or\nignored local files for sensitive values.\n\n---\n\n## 📄 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcamner%2Fmacos-scripts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcamner%2Fmacos-scripts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcamner%2Fmacos-scripts/lists"}