GO — Healthy across all four use cases

• Last commit 3d ago
• 4 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 86% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Emacs Plus is a Homebrew tap that provides GNU Emacs formulae and pre-built casks for macOS with curated defaults and optional native compilation support. It packages Emacs 26–31 with sensible '+' features enabled by default (like multi-threaded rendering, dynamic modules, native compilation on newer versions) while leaving controversial options as opt-in, eliminating the need for users to compile Emacs with custom flags. Hub-and-spoke architecture: Library/ contains shared Ruby modules (BuildConfig.rb, EmacsBase.rb, IconApplier.rb, UrlResolver.rb) used by both Formula/ (source build recipes for emacs-plus@26..@31) and Casks/ (pre-built app packages). Aliases/ symlink to default versions. GitHub Actions workflows in .github/workflows/ orchestrate builds and validation; Python helper scripts in .github/scripts/ automate version-specific updates.

macOS users (especially Emacs power-users and developers) who want a pre-built or easily compilable Emacs with modern features without managing complex build flags; maintainers and contributors to the Homebrew ecosystem who manage package formulae and CI/CD pipelines.

Actively maintained and production-ready. The repo has multiple GitHub Actions workflows (build.yml, nightly.yml, build-app.yml, validate.yml) indicating robust CI/CD, supports 6 concurrent Emacs versions (26–31), and publishes both pre-built binaries (casks) and source formulae. The presence of automated Dependabot configuration and detailed GitHub issue templates shows mature community practices.

Single-maintainer risk (d12frosted) is the primary concern for long-term sustainability, though the project is actively maintained with regular nightly builds. Build complexity is moderate—depends on Emacs source stability and macOS SDK compatibility across versions, particularly for native compilation features. No visible dependency vendoring or lock files (typical for Homebrew formulae), so upstream Emacs breakage could block releases.

Active nightly builds and automated cask SHA updates (via update_cask_sha.py). Multiple Emacs versions (latest at @31) are maintained in parallel with version-specific formulae. CI validates against multiple macOS/build configurations. Recent structure suggests ongoing native compilation support refinement and icon/theming customization (community/icons/ contains 4+ icon sets with metadata.json).

Clone and explore locally:

git clone https://github.com/d12frosted/homebrew-emacs-plus.git
cd homebrew-emacs-plus
# To install via Homebrew (after tapping):
brew tap d12frosted/emacs-plus
brew install emacs-plus@31          # source build, ~30 min
brew install --cask emacs-plus-app  # pre-built, ~1 min

Development: uses Ruby (204KB codebase), Makefile orchestration, and Shell scripting for CI.

Daily commands: Not a runnable app repo in traditional sense. To trigger local builds:

make          # runs Makefile (inspect for exact targets)
brew install ./Formula/emacs-plus@31.rb --build-from-source  # local formula install

CI is automated via GitHub Actions—see .github/workflows/build.yml for the canonical build command sequence (uses brew build with version/options matrix).

• Library/EmacsBase.rb — Core base class for all Emacs formulae; defines shared build configuration, options, and lifecycle—every formula inherits from this.
• Formula/emacs-plus@31.rb — Reference implementation of the latest Emacs formula; shows how to use EmacsBase, define patches, and configure build options.
• Library/BuildConfig.rb — Centralized build configuration and option flags; controls how Emacs is compiled across all formula versions.
• Library/IconApplier.rb — Applies custom icons to the Emacs app bundle; critical for cask builds and visual branding.
• .github/workflows/build.yml — Primary CI/CD workflow that tests, builds, and validates all formula versions on macOS.
• Casks/emacs-plus-app.rb — Cask definition for distributing Emacs Plus as a macOS application; entry point for GUI users.
• README.org — User-facing documentation covering installation, options, and troubleshooting; essential context for maintenance.

Add support for a new Emacs version

1. Copy the latest formula (e.g., emacs-plus@31.rb) to a new version file (e.g., emacs-plus@32.rb) (Formula/emacs-plus@32.rb)
2. Update the class name and version string; EmacsBase will handle the rest via inheritance (Formula/emacs-plus@32.rb)
3. Add version-specific patches in Library/EmacsBase.rb if needed (e.g., for macOS compatibility) (Library/EmacsBase.rb)
4. Update Aliases/emacs-plus to point to the new formula if it's the latest stable (Aliases/emacs-plus)
5. Add the new formula to .github/workflows/build.yml test matrix (.github/workflows/build.yml)

Add a new build option (flag) to control compilation

1. Define the option in Library/EmacsBase.rb using Homebrew's option DSL (e.g., option 'with-my-feature') (Library/EmacsBase.rb)
2. Add corresponding configure flag logic in the install method of EmacsBase.rb (Library/EmacsBase.rb)
3. Document the new option in README.org with usage examples and rationale (README.org)
4. Test the option by running brew install emacs-plus@31 --with-my-feature locally (Makefile)

Add and distribute a new custom icon theme

1. Create a new icon directory under community/icons/{icon-name}/ with icon.icns, metadata.json, and preview.png (community/icons/my-custom-icon/icon.icns)
2. Define the icon in Library/IconApplier.rb so it can be selected via --with-icon={icon-name} (Library/IconApplier.rb)
3. Update community/icons/README.md to document the new icon and its author (community/icons/README.md)
4. Commit changes; the cask build workflow will automatically package it (.github/workflows/build-app.yml)

Apply a macOS-specific patch or workaround

1. Create a .patch file in the patches/ directory (if it exists) or inline the patch in Library/EmacsBase.rb (Library/EmacsBase.rb)
2. Add conditional logic in EmacsBase.rb to apply the patch only for specific macOS versions or Emacs versions (Library/EmacsBase.rb)
3. Document the patch reason and affected versions in comments and NEWS.org (NEWS.org)
4. Run the nightly CI workflow to validate the patch across versions (.github/workflows/nightly.yml)

• Ruby + Homebrew DSL — Native integration with macOS package manager; leverages existing Homebrew infrastructure for formula definition, dependency resolution, and install lifecycle.
• GitHub Actions — Native CI/CD in GitHub; allows automated matrix testing across multiple Emacs versions and macOS runners without external service.
• GNU Emacs source tarballs — Official, stable, and auditable source; enables full control over patches and compile flags rather than relying on pre-built binaries.
• Python for SHA256 cask updates — Lightweight automation of checksum updates in cask definitions; decouples release workflow from Ruby formula logic.

• Inheritance-based architecture (EmacsBase) for all formula versions

  • Why: Reduces duplication and ensures consistent build flags/options across Emacs 26–31.
  • Consequence: Changes to EmacsBase affect all versions; requires careful testing in CI to avoid breaking older formulas.

• Community icon pack in source repo rather than separate registry

  • Why: Simplicity; users can browse and select icons without external lookups or API calls.
  • Consequence: Icon contributions are tracked in repo history; each new icon increases repo size slightly.

• Nightly builds in addition to PR/release builds

  • Why: Early detection of regressions in development Emacs versions or macOS updates.
  • Consequence: Increased CI/CD runtime and resource usage; necessary for stability guarantees.

• Custom patches applied at compile time rather than pre-built binaries

  • Why: Transparency and auditability; users can inspect what was changed and why.
  • Consequence: Slower install times (~5–10 min) compared to binary distribution; users must have build tools installed.

• Linux or Windows support; macOS-only via Homebrew.

1. Emacs source dependency: Each formula version pins to a specific Emacs release; upstream Emacs 31+ may have breaking build flags or macOS SDK incompatibilities (especially native compilation with libgccjit).
2. Code signing on ARM64/Intel: Pre-built .app casks must be notarized for macOS Gatekeeper; missing notarization blocks installation on newer macOS.
3. Build environment vars: Native compilation requires specific LIBRARY_PATH and compiler flags; see Library/BuildConfig.rb for version-specific workarounds.
4. Icon format requirements: community/icons/{Name}/icon.icns must be in exact format expected by IconApplier.rb; .sips or invalid dimensions will silently fail.
5. Homebrew tap state: Formula uses 'tap' model; local edits require brew edit or direct file modification in Homebrew's cached tap directory (~/.homebrew/Library/Taps/), not the cloned repo.
6. macOS SDK versioning: Formulae are tightly coupled to macOS SDK paths (e.g., /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX*.sdk); mismatches break native compilation builds.

• Native Compilation (libgccjit) — Emacs 28+ in this repo can use GCC's libgccjit to JIT-compile .el bytecode to native code at runtime, dramatically improving startup/runtime performance on modern macOS; understanding when/how it's enabled is critical for troubleshooting slow builds or crashes.
• Homebrew Formulae and Taps — This entire project is a Homebrew 'tap' (custom package repository) using Ruby-based formula DSL; understanding Homebrew's formula structure, option flags, and dependency resolution is foundational to modifying or extending emacs-plus.
• macOS Code Signing and Notarization — Pre-built casks (emacs-plus-app.rb) must be code-signed and notarized to install on modern macOS; breakage here prevents users from installing pre-built binaries and forces local compilation.
• Dynamic Modules (emacs-module.h API) — Emacs 25+ supports loading compiled .so/.dylib modules via emacs-module.h; this repo enables dynamic modules by default, allowing packages like pdf-tools to work without patching core Emacs.
• Multi-threaded Rendering (pthreads) — Modern emacs-plus enables pthread support in Emacs builds, allowing UI responsiveness improvements and compatibility with packages requiring concurrent Lisp execution; understanding when this is/isn't available is key for debugging hangs.
• GitHub Actions Matrix Builds — build.yml uses GitHub Actions matrix strategy to test multiple Emacs versions and macOS SDK versions in parallel; understanding matrix syntax is essential for adding/removing versions or fixing CI failures.
• macOS Bundle Structure (.app format) — Pre-built casks must package Emacs into .app bundles (Resources/, MacOS/, Info.plist structure) with icon injection; IconApplier.rb and cask formulae handle this; misunderstanding bundle structure breaks app discovery and icon display.

• emacs-mirror/emacs — Upstream GNU Emacs source; all formula versions pin to specific tags from this repo
• Homebrew/homebrew-core — Official Homebrew tap containing the default emacs formula; this repo offers a feature-rich alternative with native compilation and custom options
• railwaycat/homebrew-emacsmacport — Competing Emacs Homebrew tap (older, less maintained) that applies macport patches; both target macOS power-users
• d12frosted/homebrew-tools — Companion tap by same maintainer; may contain related build utilities or CLI tools used in emacs-plus CI/CD
• Homebrew/homebrew-bundle — Bundler-like tool for Homebrew; users often manage emacs-plus installs via Brewfiles in Homebrew/homebrew-bundle

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create comprehensive tests for Library/BuildConfig.rb configuration parsing

The Library/BuildConfig.rb file is critical to the build system but there's no visible test suite. A new contributor could add RSpec tests to validate configuration parsing, option validation, and error handling. This would prevent regressions when formula maintainers modify build configurations across emacs-plus@26 through emacs-plus@31.

• [ ] Create spec/library/build_config_spec.rb with tests for BuildConfig class initialization
• [ ] Add tests for configuration option parsing and validation logic
• [ ] Test edge cases like invalid option combinations or missing required config values
• [ ] Integrate tests into GitHub Actions workflow (update .github/workflows/validate.yml to run RSpec)

Add linting and type-checking workflow for Ruby scripts in .github/scripts/

The .github/scripts/update_cask_sha.py exists but there's a .rubocop.yml configuration file suggesting Ruby linting standards. However, there's no GitHub Action workflow that validates the Python script or runs RuboCop on Library and Formula Ruby files. This would catch style violations and potential bugs early.

• [ ] Add Python linting step to .github/workflows/validate.yml using flake8 or pylint for .github/scripts/*.py
• [ ] Add RuboCop step to validate.yml for Library/.rb and Formula/.rb files
• [ ] Create a .pre-commit-config.yaml for local developer convenience
• [ ] Document the linting setup in README.org under development section

Document and validate icon metadata schema with JSON Schema

The community/icons directory contains 9 icon sets with metadata.json files, but there's no validation that these metadata files follow a consistent schema. This could lead to invalid configurations in the IconApplier.rb library. A contributor could create a JSON Schema and validation script to ensure consistency.

• [ ] Create community/icons/schema.json defining required fields (name, version, author, license, etc.) for metadata.json
• [ ] Add a validation script to .github/scripts/validate_icon_metadata.py to check all icon metadata files
• [ ] Integrate validation into .github/workflows/validate.yml
• [ ] Update community/README.md with schema documentation and examples for icon contributors

1. Add integration tests for Library/IconApplier.rb: Currently no visible test suite for icon application logic; add RSpec tests in a new spec/ directory to verify .icns application to .app bundles and prevent regressions when adding new icon formats.
2. Document BuildConfig.rb feature flags: Create a new docs/build-flags.md explaining which Library/BuildConfig.rb variables control native compilation, modules, threading, and their macOS version requirements—currently only visible in comments.
3. Add pre-build validation in .github/workflows/validate.yml: Currently validate.yml exists but likely minimal; expand it to run brew audit on all Formula/emacs-plus@.rb files and lint Library/.rb with rubocop before build.yml runs, catching formula syntax errors earlier.

The Homebrew Emacs Plus repository demonstrates moderate security posture. Primary concerns include: (1) GitHub Actions workflows that require detailed review for secret handling and permission models, (2) Python automation scripts needing input validation review, (3) Supply chain risks from external formula dependencies requiring checksum verification, (4) Community-contributed icon files that may benefit from formal review processes. The project lacks a formal security policy document. No obvious hardcoded secrets, injection vulnerabilities, or infrastructure misconfigurations were detected based on visible file structure. Recommendations focus on workflow hardening, dependency management verification, and establishing security documentation.

• Medium · Python Script Without Apparent Input Validation — .github/scripts/update_cask_sha.py. The file '.github/scripts/update_cask_sha.py' is a Python script that updates cask checksums. Without access to the source code, potential risks include: insufficient input validation, unsafe file operations, or command injection if it processes external data or user inputs. Fix: Review the script for proper input validation, sanitization of any external inputs, safe file handling practices, and avoid using subprocess with shell=True. Implement comprehensive error handling.
• Medium · GitHub Actions Workflow Security — .github/workflows/. Multiple GitHub Actions workflows (.github/workflows/*.yml) are present but cannot be fully analyzed without content. Potential risks include: insecure use of secrets, insufficient permission scopes, untrusted action versions, or checkout of untrusted code in PR workflows. Fix: Review all workflows to: (1) Use specific action versions with SHA pinning, (2) Implement least-privilege permission model with explicit permissions blocks, (3) Use GitHub's OIDC provider instead of long-lived tokens where possible, (4) Add content trust verification for external dependencies.
• Low · Potential Supply Chain Risk - Homebrew Formula Dependencies — Formula/ directory (multiple .rb files). The repository contains multiple Emacs Plus formulae (emacs-plus@26 through @31) that likely specify external dependencies. Without seeing dependency specifications, there's a risk of: outdated dependencies, unvetted upstream sources, or lack of checksum verification. Fix: Ensure all dependencies: (1) Use SHA256 checksums for downloaded sources, (2) Specify exact versions rather than ranges, (3) Regularly audit and update dependencies, (4) Verify upstream source authenticity.
• Low · Community Icons Directory Trust — community/icons/. The 'community/icons/' directory contains user-contributed icon files (ICNS, PNG) which could potentially be modified or contain malicious content. Binary icon files are difficult to audit. Fix: Implement a contribution review process for icon submissions. Consider: (1) Requiring signed contributions, (2) Scanning binary files with antivirus tools, (3) Documenting the icon source and licensing clearly in metadata.json files.
• Low · Missing Security Configuration Files — Root directory. No evidence of security-related configuration files such as SECURITY.md (security policy), .github/SECURITY.md, or CODEOWNERS to manage security responsibilities and vulnerability reporting. Fix: Create a SECURITY.md file documenting: (1) How to report security vulnerabilities responsibly, (2) Security response timeline, (3) Supported versions, (4) Recommended security practices for users.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/d12frosted/homebrew-emacs-plus shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live d12frosted/homebrew-emacs-plus repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/d12frosted/homebrew-emacs-plus.

What it runs against: a local clone of d12frosted/homebrew-emacs-plus — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in d12frosted/homebrew-emacs-plus | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of d12frosted/homebrew-emacs-plus. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/d12frosted/homebrew-emacs-plus.git
#   cd homebrew-emacs-plus
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of d12frosted/homebrew-emacs-plus and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "d12frosted/homebrew-emacs-plus(\\.git)?\\b" \\
  && ok "origin remote is d12frosted/homebrew-emacs-plus" \\
  || miss "origin remote is not d12frosted/homebrew-emacs-plus (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Library/EmacsBase.rb" \\
  && ok "Library/EmacsBase.rb" \\
  || miss "missing critical file: Library/EmacsBase.rb"
test -f "Formula/emacs-plus@31.rb" \\
  && ok "Formula/emacs-plus@31.rb" \\
  || miss "missing critical file: Formula/emacs-plus@31.rb"
test -f "Library/BuildConfig.rb" \\
  && ok "Library/BuildConfig.rb" \\
  || miss "missing critical file: Library/BuildConfig.rb"
test -f "Library/IconApplier.rb" \\
  && ok "Library/IconApplier.rb" \\
  || miss "missing critical file: Library/IconApplier.rb"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/d12frosted/homebrew-emacs-plus"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.