maccat — Catálogo de Software macOS
scottkw/maccat
Inventário completo e versionável de software e tooling do macOS
Ver no GitHubFerramenta que cataloga automaticamente todo software, extensões, plugins e MCP servers instalados em seu Mac. Gera registros em Markdown versionáveis via Git, com seções para aplicações, ferramentas de IA, extensões de editores e navegadores. Inclui recurso de reinstalação determinística a partir do catálogo.
Instalação
npx convez-ai scottkw/maccat1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter registro histórico de ambiente de desenvolvimento
- Documentar setup reproducível entre múltiplos Macs
- Auditar extensões e plugins instalados
- Facilitar onboarding com script de reinstalação automática
- Controlar versão de configuração de máquina via Git
Veredito

Ferramenta sólida para infraestrutura local em macOS, especialmente útil para times que precisam manter ambientes sincronizados e documentados. O suporte nativo a MCP servers e AI coding CLIs é diferencial relevante para o ecossistema Claude.
README
A tradução para o português deste README ainda está na fila.
maccat
A Python tool that catalogs all software and developer tooling installed on your macOS machine — applications, plus the extensions, plugins, MCP servers, and skills/agents of your AI coding CLIs, editors, and browsers. Each catalog is named with a friendly machine label you choose, each run keeps only the newest catalog per machine in the main folder, archives the rest, auto-prunes the archive after a configurable number of days (default 30), and syncs every change via git.
Catalogs are written as rendered Markdown (.md) — a YAML frontmatter block (computer, hostname, generated timestamp, maccat version) followed by one ## section per source, each a uniform Name | Version | ID table. The output stays deterministic and stably sorted, so two unchanged runs diff cleanly.
It can also work in reverse: maccat reinstall turns a catalog back into a reviewable reinstall.sh — a never-auto-executed script that reinstalls the deterministic sources (Homebrew, Mac App Store, VS Code/Cursor extensions) and lists everything else as a manual checklist. Legacy plain-text (.txt) catalogs from before v3.0.0 are upgraded to the new format with maccat convert.
Format change in v3.0.0: catalogs moved from plain text (
.txt) to Markdown (.md).reinstallconsumes.mdonly; runconverton any older.txtcatalog first.
Overview
This tool generates comprehensive Markdown (.md) catalogs of your installed software and tooling from multiple sources — 22 sections in total:
Applications
- Homebrew packages (formulae and casks)
- Mac App Store applications (via the
masCLI) - Setapp applications
- Web-installed applications (DMG, PKG, direct downloads)
AI coding CLI tooling (name + version + ID where available)
- Claude Code — plugins, MCP servers, and skills/agents
- Codex — MCP servers and plugins
- OpenCode — plugins, MCP servers, and agents
- Gemini CLI — extensions and MCP servers
Editor extensions
- VS Code, Cursor, and Zed — installed extensions (human-readable display names resolved)
Browser extensions (across all profiles)
- Google Chrome, Microsoft Edge, and Brave — user-installed extensions (built-in components excluded via per-browser denylists)
- Firefox — user-installed extensions and themes (built-in/system add-ons excluded)
- Safari — user-installed web extensions (via
pluginkit+ per-.appexInfo.plist)
Each catalog is timestamped and named with a friendly machine label you choose (see Machine Identity) for easy identification across multiple Macs. Every source degrades gracefully — if a tool or browser isn't installed, its section renders (none found) and the run continues.
Privacy: MCP server entries capture name + transport type only (e.g.
my-server [stdio]). Environment values, headers, tokens, and auth-bearing URLs are never written to the catalog — the file is git-committed and pushed, so secrets must not leak into it.
Installation
maccat ships as a self-contained Python zipapp (.pyz). No installation of the package itself is needed — download the file and run it directly.
Requirements: Python >= 3.11, macOS.
Download from GitHub Releases
- Go to the Releases page and download the latest
maccat.pyz. - Make it executable (optional but convenient):
chmod +x maccat.pyz - Run it:
python3 maccat.pyz --catalog-dir /path/to/your/catalog-repo # or, if executable: ./maccat.pyz --catalog-dir /path/to/your/catalog-repo
The catalog repo is a separate git repository where maccat writes its snapshot files. You can create a new one or use an existing repo — maccat just needs a directory with a git remote configured.
Configuration
maccat needs to know where your catalog repo lives. Resolution order (highest priority first):
--catalog-dir <path>— command-line flag (takes precedence over everything)MACCAT_CATALOG_DIR— environment variable~/.config/maccat/config.toml— config file (catalog_dirkey)- Error — if none of the above is set, maccat exits with an error
Config file
Copy config.example.toml to ~/.config/maccat/config.toml and set catalog_dir:
catalog_dir = "/path/to/your/catalog-repo"
See config.example.toml for the full template with comments.
Usage
Basic run
# Using the config file (~/.config/maccat/config.toml)
python3 maccat.pyz
# Explicitly specify the catalog repo
python3 maccat.pyz --catalog-dir ~/my-catalog-repo
# Using the environment variable
MACCAT_CATALOG_DIR=~/my-catalog-repo python3 maccat.pyz
If no computer-folder argument is provided, you'll be prompted to choose a folder:
Where would you like to save this catalog?
1) home
2) work
Enter your choice (1 or 2):
Or specify it directly:
# Skip the interactive folder-selection prompt
python3 maccat.pyz --computer MyMac
Options
| Option | Description |
|---|---|
--computer NAME | Select (or create) the named computer-folder non-interactively |
--catalog-dir <path> | Path to the catalog git repository (overrides config and env) |
--no-commit | Skip automatic git commit and push |
--archive-days N | Set the archive-retention period in days for this run (default: 30) |
--rename | Separate mode: rename a machine label across all catalog files, then commit |
Reinstall from a catalog
The reinstall subcommand reads a catalog back and generates a reinstall.sh script in the current directory that can rebuild a machine's software from the snapshot. The script is never run for you — it's written non-executable (mode 0644) and printed for you to review and run yourself.
# Use an explicit catalog file (must be a Markdown .md catalog)
python3 maccat.pyz reinstall --from /path/to/mac-software-list-[home]-20260616120000.md
# Or omit --from: pick a computer interactively and use its newest catalog
python3 maccat.pyz reinstall
# Non-interactive: pick a computer by name (uses that folder's newest catalog)
python3 maccat.pyz --catalog-dir ~/my-catalog-repo reinstall --computer home
maccat prints the absolute path of the generated script:
/Users/you/reinstall.sh
What the script does:
- Auto-installs the deterministic sources with idempotent, re-runnable, guarded commands:
- Homebrew —
brew list <n> &>/dev/null || brew list --cask <n> &>/dev/null || brew install <n>(one command covers formulae and casks) - Mac App Store —
mas install <id>for apps whose numeric App Store ID is in the catalog (guarded so an already-installed app doesn't abort the run) - VS Code / Cursor extensions —
code/cursor --install-extension <id>behind acommand -vPATH guard and a--list-extensionsidempotency check - Each line carries the cataloged version as a
# cataloged: …comment (it installs the latest version, not a pin).
- Homebrew —
- Lists everything else as a manual checklist (no fabricated install commands): Setapp apps, web-installed
/Applications, Chrome/Firefox extensions, and all AI-CLI MCP servers / plugins / skills / agents (these are cataloged as identity-only for privacy, so there's nothing to auto-install). - Opens with
#!/usr/bin/env bash+set -Eeuo pipefailand a provenance header naming the source catalog and generation date. Every catalog-derived value is shell-quoted, so it's safe to generate from any catalog.
Note: App Store entries are only auto-installed when the catalog records their numeric ID. Catalogs generated before v2.1.0 don't have it, so those apps fall into the manual checklist instead.
Markdown-only (v3.0.0+):
reinstallreads the Markdown (.md) format exclusively. Handed a legacy.txtcatalog — or a.mdfile missing valid frontmatter — it exits with a clear error directing you tomaccat convert --from PATHfirst. It never silently part-parses an old catalog.
| Subcommand | Description |
|---|---|
reinstall [--from PATH] | Generate reinstall.sh from a Markdown catalog (explicit --from, else the computer picker uses the newest catalog; --computer NAME selects non-interactively) |
convert --from PATH | Upgrade one legacy .txt catalog to the new .md format in place (see Convert a legacy catalog) |
Convert a legacy catalog
The convert subcommand upgrades a single legacy plain-text (.txt) catalog to the new Markdown (.md) format. It reads the .txt through the retained legacy parser, rewrites the full contents — every section and every item's name / version / ID — through the same Markdown emitter used by catalog generation, writes the .md, removes the old .txt, and stages both changes in one commit.
# Convert one legacy catalog (writes the .md, removes the .txt, commits both)
python3 maccat.pyz convert --from /path/to/mac-software-list-[home]-20260616120000.txt
# Do the file operations without committing to git
python3 maccat.pyz convert --from /path/to/old-catalog.txt --no-commit
- Frontmatter is synthesized from the current machine at conversion time:
computeris parsed from the filename, whilegenerated(now),hostname, andmaccat_versionreflect the machine runningconvert. The output keeps the original filename timestamp (only the extension changes,.txt→.md). - Safe and non-destructive: the
.txtis removed only after the.mdis written successfully. If the target.mdalready exists, convert errors rather than overwriting it. Missing, unreadable, or unrecognizable input aborts cleanly with a clear error — convert never fabricates data and never executes anything. - Single-file only. Bulk / folder-wide conversion is not yet supported.
| Subcommand | Description |
|---|---|
convert --from PATH | Convert one legacy .txt catalog to .md (in-place replace + single commit; --no-commit does the file ops only) |
Machine Identity
Catalog files are named with a friendly machine label you choose, instead of the raw hostname. Each Mac remembers its label, so you're only prompted the first time.
How the label is resolved
On each run, the label is resolved in this order:
-
--computer NAMEflag — used as-is for this run, and saved to the map. -
Saved entry — if this machine's hostname is already in
machine-labels.tsv, its label is used automatically with no prompt. -
Interactive menu — on a new machine with no saved label, you get a numbered menu of all known labels plus a "Create new label" option:
Select a machine label for this run: 1) My Laptop 2) Work iMac 3) Create new label Enter your choice (1-3):Whatever you pick (existing label or a new one you type) is saved, so subsequent runs on this machine resolve it automatically.
The hostname → label map
Mappings live in machine-labels.tsv at the catalog repo root — a git-tracked, tab-delimited file (hostname<TAB>label, one per line; # comments and blank lines are ignored). Because it's committed, every machine converges on the same roster of labels when it pulls, which powers the selection menu and the rename feature.
Labels may contain spaces, apostrophes, letters, digits, and - _ . — but not /, [, ], tabs, or newlines, and not leading/trailing whitespace. Invalid labels are rejected with an error.
Non-interactive runs (cron, piped stdin) on a machine with no saved label and no --computer flag fail fast with a clear error rather than hanging — pass --computer NAME in that case.
Renaming a Machine
--rename is a separate mode (it doesn't generate a catalog) that rewrites a machine label everywhere it appears — across all computer-folders and their archives — in a single self-committing operation:
python3 maccat.pyz --rename
It pulls the latest changes, presents a menu of known labels, asks for the new label, and then:
- Renames every matching
mac-software-list-[OLD]-...mdto[NEW]across all directories (preserving timestamps). - Updates the
machine-labels.tsventry to the new label. - Stages all the moves plus the map change and commits/pushes in one commit.
Safety behavior:
- If a destination filename already exists, that individual file is skipped (never overwritten) and reported.
- If no files match the chosen label anywhere, nothing is changed — no map edit, no commit.
--renamerequires an interactive terminal; combine with--no-committo perform the renames on disk without committing.
Retention & Archiving
On every run, maccat keeps the selected computer-folder lean and self-prunes its archive. Two operations run automatically, scoped to the folder you targeted — the other folder is never touched:
1. Keep newest-per-machine (retention)
- The main folder keeps only the newest catalog per machine — one current snapshot per label.
- All older catalogs for each machine are moved into that folder's
archive/subfolder.
2. Prune the archive (configurable retention, default 30 days)
- Catalogs in
archive/whose filename timestamp is older than the retention period are hard-deleted from disk. - The retention period defaults to 30 days. Set it per run with
--archive-days N. - Age is determined by the timestamp in the filename; an unparseable filename is skipped (never deleted).
Both operations degrade gracefully — an empty folder, a missing archive/ directory, or an unparseable filename never aborts the run, and the newest catalog for each machine is never archived or deleted.
Git Integration
By default, maccat automatically commits and pushes changes to git after generating a catalog:
- Auto-commit: The new catalog file is automatically committed with a detailed message
- Auto-push: Changes are pushed to the remote repository
- All changes in one commit: The commit stages the entire targeted folder, so the new catalog, catalogs moved to
archive/, catalogs removed by the archive prune, and any new/changed machine-label mapping are all synced together.
Commit Message Format
Added personal catalog for [<machine-label>] at YYYYMMDDHHMMSS
Disabling Auto-commit
python3 maccat.pyz --no-commit
The retention and archive prune still run on disk with --no-commit — only the git commit/push step is skipped.
Output
maccat generates a Markdown file named:
mac-software-list-[<machine-label>]-YYYYMMDDHHMMSS.md
For example: mac-software-list-[My Laptop]-20260601153045.md
Each file opens with a YAML frontmatter block carrying provenance, followed by a # title and one ## section per source:
---
computer: "My Laptop"
hostname: "my-laptop.local"
generated: "2026-06-01T15:30:45"
maccat_version: "3.1.0"
---
Catalog Contents
Each catalog contains 22 sections, in this order:
Applications
- Homebrew Packages — all formulae and casks installed via Homebrew
- App Store Applications — apps installed from the Mac App Store
- Setapp Applications — apps from the Setapp subscription service
- Web-installed Applications — other apps in /Applications
AI coding CLI tooling
- Claude Code Plugins / Claude Code MCP Servers / Claude Code Skills & Agents
- Codex MCP Servers / Codex Plugins
- OpenCode Plugins / OpenCode MCP Servers / OpenCode Agents
- Gemini CLI Extensions / Gemini CLI MCP Servers
Editor extensions
- VS Code Extensions / Cursor Extensions / Zed Extensions
Browser extensions (all profiles)
- Google Chrome Extensions / Microsoft Edge Extensions / Brave Browser Extensions / Firefox Extensions / Safari Extensions
Every section renders as a ## heading containing a three-column Name | Version | ID table; a missing version or ID renders as an empty cell, and a source with no items renders (none found) under its heading. Rows are stably sorted and the output is byte-deterministic, so two consecutive runs on an unchanged machine produce an identical catalog (an empty diff). MCP server / plugin / skill entries are identity-only (no secrets — see the privacy note above).
Example Output
---
computer: "My Laptop"
hostname: "my-laptop.local"
generated: "2026-06-01T15:30:45"
maccat_version: "3.1.0"
---
# Installed Mac Software List
## Homebrew Packages
| Name | Version | ID |
| --- | --- | --- |
| autoconf | 2.73 | |
| awscli | 2.35.7 | |
| git | 2.44.0 | |
## App Store Applications
| Name | Version | ID |
| --- | --- | --- |
| Amphetamine | 5.3.2 | 937984704 |
| Bitwarden | 2026.5.0 | 1352778147 |
| Xcode | 15.0 | 497799835 |
## Codex Plugins
(none found)
## VS Code Extensions
| Name | Version | ID |
| --- | --- | --- |
| Auto Rename Tag | 0.1.10 | formulahendry.auto-rename-tag |
| Claude Code for VS Code | 2.1.181 | anthropic.claude-code |
## Google Chrome Extensions
| Name | Version | ID |
| --- | --- | --- |
| Bitwarden Password Manager | 2026.5.1 | nngceckbapebfimnlniiiahkandclblb |
| Claude | 1.0.77 | fcoeoabgfenejglbffodgkkbkcdhcgfn |
Prerequisites
maccat reads on-disk config and manifests for the tools it catalogs — no separate integration setup is needed. The following optional tools extend what maccat can catalog:
-
Homebrew — for listing brew packages
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -
mas (Mac App Store CLI) — for listing App Store apps
brew install mas -
jq — preferred JSON parser; falls back to the built-in
/usr/bin/plutilif absentbrew install jq
No setup is needed for the AI CLIs (Claude Code, Codex, OpenCode, Gemini), editors (VS Code, Cursor, Zed), or browsers (Chrome, Edge, Brave, Firefox, Safari) — maccat auto-detects whichever are installed and silently skips the rest.
maccat was originally implemented as a Zsh script and ported to Python in v1.0.0.
Troubleshooting
"mas is not installed" warning
brew install mas
"Homebrew is not installed" warning
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Permission denied running maccat.pyz
chmod +x maccat.pyz
License
MIT — see LICENSE.