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/AppHouseKitchen/AlDente-Battery_Care_and_Monitoring 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.

WAIT — Single-maintainer risk — review before adopting

• Last commit 4w ago
• 11 active contributors
• Other licensed
• ⚠ Single-maintainer risk — top contributor 89% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

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

What it runs against: a local clone of AppHouseKitchen/AlDente-Battery_Care_and_Monitoring — 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 AppHouseKitchen/AlDente-Battery_Care_and_Monitoring | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 57 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of AppHouseKitchen/AlDente-Battery_Care_and_Monitoring. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/AppHouseKitchen/AlDente-Battery_Care_and_Monitoring.git
#   cd AlDente-Battery_Care_and_Monitoring
#
# 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 AppHouseKitchen/AlDente-Battery_Care_and_Monitoring and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "AlDente/AppDelegate.swift" \\
  && ok "AlDente/AppDelegate.swift" \\
  || miss "missing critical file: AlDente/AppDelegate.swift"
test -f "AlDente/ContentView.swift" \\
  && ok "AlDente/ContentView.swift" \\
  || miss "missing critical file: AlDente/ContentView.swift"
test -f "com.davidwernhart.Helper/HelperTool.swift" \\
  && ok "com.davidwernhart.Helper/HelperTool.swift" \\
  || miss "missing critical file: com.davidwernhart.Helper/HelperTool.swift"
test -f "com.davidwernhart.Helper/SMC.swift" \\
  && ok "com.davidwernhart.Helper/SMC.swift" \\
  || miss "missing critical file: com.davidwernhart.Helper/SMC.swift"
test -f "Common/HelperToolProtocol.swift" \\
  && ok "Common/HelperToolProtocol.swift" \\
  || miss "missing critical file: Common/HelperToolProtocol.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 57 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~27d)"
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/AppHouseKitchen/AlDente-Battery_Care_and_Monitoring"
  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).

AlDente is a macOS menubar utility written in Swift that limits battery charging percentage (20–100%) to extend MacBook battery lifespan by keeping Li-Ion cells in the optimal 20–80% range. It communicates with system management controller (SMC) via a privileged helper tool (HelperTool.swift) to intercept and stop charging at user-defined thresholds, solving the problem of degraded battery health from prolonged 100% charging. Hybrid Xcode project: AlDente/ contains the user-facing Swift UI (AppDelegate.swift, ContentView.swift, PersistanceManager.swift) and assets; com.davidwernhart.Helper/ is the privileged companion daemon (main.swift, HelperTool.swift, SMC.swift) installed via SMJobBless; Common/HelperToolProtocol.swift defines the IPC contract between app and helper; SMJobBlessUtil.py is a one-off build-time utility.

MacBook owners (especially those on long power supply duty) who want to maximize battery longevity without paying for the Pro version; contributors are macOS systems engineers interested in SMC communication, privilege escalation (SMJobBless), and battery management APIs.

Actively developed and production-ready: the repo has a clear release structure (GitHub Releases), established GitHub Issues templates (bug_report.md, feature_request.md), and a paid Pro tier (apphousekitchen.com), indicating commercial maturity. However, the single-contributor history (davidwernhart) and limited public test suite visibility suggest small core team; macOS 11+ requirement indicates versioning discipline.

Single-point-of-failure risk around SMC communication (SMC.swift) and helper tool lifecycle—bugs here brick the charge-limiting feature. Privileged helper tool requires SMJobBless framework (SMJobBlessUtil.py), which is notoriously fragile across macOS versions; no visible CI/CD pipeline or automated tests in the file list suggests manual release process. Dependency on Info.plist and launchd configuration (Helper-Launchd.plist) creates hidden configuration gotchas.

Repository structure and file timestamps suggest ongoing maintenance: project uses modern SwiftUI (ContentView.swift), userdata tracking (xcuserstate) indicates frequent Xcode sessions, and the Pro upsell strategy (README.md references Setapp integration and advanced features like Heat Protection, Sailing Mode) suggests active feature development. No live PR or issue data visible, but the presence of three GitHub issue templates indicates triage infrastructure.

Clone the repo: git clone https://github.com/AppHouseKitchen/AlDente-Battery_Care_and_Monitoring.git && cd AlDente-Battery_Care_and_Monitoring. Open in Xcode: open AlDente.xcodeproj. Build the main app target (AlDente) and helper daemon (com.davidwernhart.Helper). Installation requires code signing and SMJobBless setup (see Installation Guide link in README).

Daily commands: After cloning, open AlDente.xcodeproj in Xcode, select the AlDente scheme, and press Cmd+R. The app will appear in the macOS menubar (top-right clock area). First run requires granting privileged helper install (system prompt). To test locally, you must code-sign the app and helper with a valid macOS development certificate.

• AlDente/AppDelegate.swift — Application entry point and menubar lifecycle management—controls app initialization, window handling, and system integration.
• AlDente/ContentView.swift — Main UI view hierarchy using SwiftUI—contains the core UI for charge limit controls and battery status display.
• com.davidwernhart.Helper/HelperTool.swift — Privileged helper daemon that directly interfaces with SMC to enforce charge limits—requires privileged execution and system authorization.
• com.davidwernhart.Helper/SMC.swift — System Management Controller interface—low-level hardware communication for reading battery status and setting charge limits.
• Common/HelperToolProtocol.swift — IPC protocol definition between main app and privileged helper—defines all commands and responses for inter-process communication.
• AlDente/PersistanceManager.swift — Local preference storage and retrieval—manages user settings persistence across app launches.
• AlDente/Helper.swift — Main app helper logic and IPC coordination—bridges UI commands to the privileged helper tool via XPC.

• ContentView (SwiftUI) (SwiftUI, @ObservedObject, Binding) — Renders charge limit slider, battery percentage, and status labels; binds to Helper @Published properties
  • Failure mode: If Helper connectivity fails, UI becomes unresponsive; slider changes won't propagate to SMC
• Helper.swift (IPC Coordinator) (NSXPCConnection, @Published, Codable) — Maintains XPC connection to privileged daemon; sends commands and receives responses; caches battery state
  • Failure mode: If XPC connection is refused (daemon not installed or no entitlements), all SMC

Add a new battery monitoring metric

1. Add a new SMC key query method in SMC.swift to read the metric from hardware (com.davidwernhart.Helper/SMC.swift)
2. Add a new XPC command to HelperToolProtocol.swift to expose the metric over IPC (Common/HelperToolProtocol.swift)
3. Implement the new command handler in HelperTool.swift (com.davidwernhart.Helper/HelperTool.swift)
4. Call the new XPC command from Helper.swift and expose via @Published property (AlDente/Helper.swift)
5. Display the metric in ContentView.swift using SwiftUI bindings (AlDente/ContentView.swift)

Add a new user preference setting

1. Add a new UserDefaults key and @Published property in PersistanceManager.swift (AlDente/PersistanceManager.swift)
2. Add a new UI control (toggle, slider, etc.) in ContentView.swift bound to the preference (AlDente/ContentView.swift)
3. If the preference affects battery behavior, add a new XPC command to HelperToolProtocol.swift (Common/HelperToolProtocol.swift)
4. Implement preference-dependent logic in HelperTool.swift to apply SMC changes based on the preference (com.davidwernhart.Helper/HelperTool.swift)

Modify SMC charge limit enforcement logic

1. Update the charge limiting algorithm in SMC.swift with new key writes or read sequences (com.davidwernhart.Helper/SMC.swift)
2. Modify the command handler in HelperTool.swift to call the updated SMC methods (com.davidwernhart.Helper/HelperTool.swift)
3. Test the new logic by invoking via Helper.swift and verifying in ContentView.swift (AlDente/Helper.swift)

• SwiftUI — Modern native macOS UI framework—provides real-time data binding, dark mode support, and menubar integration without Cocoa boilerplate
• XPC (XPC Services) — Apple's standard for secure inter-process communication—enables privilege separation by running SMC code in a separate root-level daemon
• SMJobBless — Apple's standard helper installation mechanism—automatically manages helper daemon installation and authorization without manual privileged operations
• System Management Controller (SMC) — Hardware interface—the only way to read battery metrics and enforce charge limits on Intel/Apple Silicon Macs at the firmware level
• UserDefaults — Standard macOS preference storage—simple key-value persistence for charge limit settings across app launches

• Separate privileged helper daemon vs. inline privilege escalation

  • Why: Privilege separation is a security best practice—only the SMC operations run as root, minimizing attack surface
  • Consequence: Adds IPC complexity and deployment overhead (helper installation), but prevents entire UI layer from running privileged

• SMC I/O at kernel level vs. IOKit user-space API

  • Why: macOS does not expose SMC charge limits via public IOKit APIs—direct SMC key-value operations are the only method
  • Consequence: Tight coupling to undocumented SMC key names; firmware updates can break key compatibility without warning

• Menubar-only UI vs. window+menubar

  • Why: Memory efficiency and user simplicity—menubar tool is always accessible and minimizes background resource usage
  • Consequence: Limited screen real estate for advanced features; forces UI simplification that may limit future feature expansion

• Synchronous XPC calls vs. async callbacks

  • Why: Simpler code flow and immediate feedback for charge limit changes—battery state is fast
  • Consequence: UI thread can block briefly during SMC operations; unsuitable for high-latency operations (mitigated by fast SMC I/O ~1–2ms)

• Does not provide cross-platform support (macOS-only due to SMC hardware dependency)
• Does not support Linux or Windows (SMC is Apple hardware-specific)
• Does not implement battery calibration or diagnostics (not exposed via public SMC APIs)
• Does not integrate with iCloud sync (uses local UserDefaults only)
• Does not support multi-user concurrent charge limit management (single-user menubar tool design)

1. SMC register offsets are hardware-specific: SMC.swift hardcodes register addresses; models not in AlDente's whitelist (see FAQ link) will fail silently or crash. 2. Code signing is mandatory: helper tool must be signed with exact same cert as app; mismatched certs break SMJobBless at runtime. 3. Helper tool launchd persistence: Helper-Launchd.plist must be identical every build; manual plist edits in Xcode can corrupt the embedded version. 4. XPC sandbox: app and helper communicate via XPC; if either crashes, the other loses all control and must restart manually. 5. No test suite visible: no unit tests or integration tests in file list; SMC changes are dangerous and untested.

• SMC (System Management Controller) — AlDente's entire charge-limiting feature depends on reading/writing SMC registers via IOKit; understanding SMC firmware protocols is critical for debugging model-specific failures
• SMJobBless (Service Management Job Bless) — AlDente uses SMJobBless to elevate the helper daemon to root privileges without prompting the user repeatedly; critical for IPC security and launchd integration
• XPC (XNU Interprocess Communication) — AppDelegate and HelperTool communicate via XPC; understanding message serialization and sandbox restrictions is needed to extend IPC protocol
• Li-Ion battery chemistry (voltage vs. capacity curve) — AlDente's 20–80% charge window is based on Li-Ion degradation kinetics; understanding open-circuit voltage thresholds explains why charge limits are hardware-specific
• Launchd daemon lifecycle and plist configuration — Helper tool runs as a persistent launchd daemon; understanding KeepAlive, StandardOutPath, and MachServices in Helper-Launchd.plist is essential for reliability
• IOKit kernel framework and ioreg device trees — SMC.swift uses IOKit to discover and communicate with the SMC device; ioreg is the debugging tool for hardware discovery and register introspection
• Code signing and notarization for macOS app distribution — AlDente's helper tool must be code-signed with the same certificate as the app for SMJobBless to work; notarization is required for Gatekeeper on modern macOS

• apple/darwin-xnu — SMC communication in AlDente relies on low-level Darwin kernel APIs; understanding IOKit and mach ports is essential for debugging register access
• jheiser/SMCKit — Swift library for SMC communication; AlDente implements custom SMC.swift, but SMCKit is a reference for cross-model register compatibility
• masterzen/OSXvpc — Another battery management tool for macOS; shows alternative approaches to charge limiting without privileged helpers
• zhuowei/DiskArbitrationKit — Example of SMJobBless privilege escalation pattern; useful for understanding the helper tool install mechanism used by AlDente
• AppHouseKitchen/AlDente-Pro — Paid companion product with Heat Protection and Sailing Mode features; likely shares codebase for SMC communication and charge logic

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.

Add unit tests for SMC.swift battery control logic

The SMC.swift file handles critical hardware interactions for setting charge limits via the System Management Controller. Without tests, regressions in charge limit setting, threshold validation, or error handling could go undetected. This is high-risk code that directly affects battery health.

• [ ] Create AlDenteTests target if not present
• [ ] Add unit tests in Tests/SMCTests.swift covering: valid charge limit ranges (20-100%), invalid inputs, SMC communication failures, and edge cases
• [ ] Test Helper.swift utility functions used by SMC operations
• [ ] Add CI workflow to run tests on pull requests

Implement GitHub Actions workflow for automated code signing and build verification

The project is a macOS app requiring code signing and distribution. Currently no CI workflow exists (.github/workflows/ is empty). This prevents automated verification of builds before merges, risking broken releases. New contributors cannot verify their changes work without building locally.

• [ ] Create .github/workflows/build.yml to compile AlDente.xcodeproj on macOS runners
• [ ] Add code signing using temporary certificates for PR validation (without distribution signing)
• [ ] Include linting checks on Swift files (SwiftLint integration via xcodeproj or brew)
• [ ] Verify Helper tool (com.davidwernhart.Helper) compiles correctly as part of the build matrix

Add comprehensive documentation for PersistanceManager.swift state persistence and SMC integration

PersistanceManager.swift stores charge limit preferences and state, but no documentation exists explaining how settings persist across app launches, how they sync with the Helper tool, or recovery behavior if settings corrupt. This creates friction for contributors modifying battery control logic.

• [ ] Create docs/ARCHITECTURE.md explaining the HelperToolProtocol communication between AlDente and com.davidwernhart.Helper
• [ ] Document PersistanceManager.swift: data format, storage location, recovery mechanisms, and thread-safety considerations
• [ ] Add inline code comments to AppDelegate.swift launch sequence showing initialization order of PersistanceManager and SMC
• [ ] Document Info.plist and Helper-Launchd.plist roles in privileged helper tool registration

• Add unit tests for PersistanceManager.swift: No tests visible for state persistence logic; testing UserDefaults read/write and type conversions would catch encoding bugs
• Document SMC.swift register offsets per MacBook model (M1/M2/Intel): SMC.swift hardcodes register addresses but no comments explain which models use which offsets; add a table or enum mapping model identifiers to register maps
• Add error UI feedback when helper tool IPC fails: If helper daemon crashes, user sees no error in menubar; add retry logic and error toast notification to ContentView.swift when XPC calls fail
• Create CI/CD workflow to code-sign and release app binaries: .github/ISSUE_TEMPLATE exists but no Actions workflows; add a GitHub Actions job to build, notarize, and release .dmg files on tag push
• Add inline documentation to HelperToolProtocol.swift XPC methods: Protocol defines IPC contract but lacks docstrings; document each method's purpose, parameter constraints, and SMC side effects for future maintainers

AlDente demonstrates reasonable security posture as a macOS menu bar utility with privilege escalation handling through a helper tool. The primary concerns are around the privileged helper tool's IPC communication security and proper code signing validation. The application correctly uses a separate privileged helper (SMJobBless pattern) rather than embedding privilege escalation in the main app. No hardcoded secrets, injection vulnerabilities, or obvious misconfigurations were detected. Secondary concerns include best practice violations like committed user-specific Xcode configurations and incomplete security policy documentation. For a battery management tool requiring system-level access, the architecture is generally sound but would benefit from comprehensive XPC validation and improved security documentation.

• Medium · Privileged Helper Tool without Code Signing Verification — com.davidwernhart.Helper/HelperTool.swift, com.davidwernhart.Helper/main.swift, SMJobBlessUtil.py. The codebase includes a privileged helper tool (com.davidwernhart.Helper) that requires elevated privileges to modify system battery settings. The presence of SMJobBlessUtil.py and helper tool setup suggests a privileged execution context. Without verified code signing and secure IPC validation, this could be exploited for privilege escalation attacks. Fix: Ensure the helper tool is properly code-signed with a valid developer certificate. Implement strict validation of IPC messages from the main application. Use XPC services with proper entitlements and sandbox restrictions. Verify the calling application's signature before executing privileged operations.
• Medium · Potential Insecure XPC/IPC Communication — Common/HelperToolProtocol.swift, com.davidwernhart.Helper/HelperTool.swift. The application implements privileged operations through a helper tool. If XPC communication between the main app and helper tool is not properly secured, it could allow unauthorized privilege escalation or command injection attacks from malicious processes. Fix: Implement proper XPC connection validation with entitlements verification. Use secure coding practices for message serialization. Validate and sanitize all input from IPC messages. Use NSXPCConnection with proper service principal name validation.
• Low · User-Specific Build Configuration Committed — AlDente.xcodeproj/xcuserdata/davidwernhart.xcuserdatad/. Xcode user data and workspace configurations (xcuserdata directories with davidwernhart.xcuserdatad) are committed to the repository. While not directly a security vulnerability, this is a best practice violation that could expose personal development paths or sensitive IDE configurations. Fix: Add xcuserdata directories to .gitignore. Remove user-specific configurations from version control. Use repository-level shared schemes instead of user-specific schemes.
• Low · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file appears to be truncated with incomplete information about update timelines and resolution procedures. This incomplete documentation could create confusion about security incident handling processes. Fix: Complete the security policy documentation with: expected timeline for security fixes, disclosure timeline expectations, and acknowledgment/credit procedures. Provide clear communication channels and escalation procedures.
• Low · SMC Direct Hardware Access — com.davidwernhart.Helper/SMC.swift. The codebase includes direct SMC (System Management Controller) access (SMC.swift) to control battery charging. Direct hardware manipulation without adequate input validation or error handling could potentially cause unexpected system behavior. Fix: Implement comprehensive input validation for all SMC commands. Add proper error handling and recovery mechanisms. Include logging for SMC operations for audit trails. Test edge cases and error conditions thoroughly.

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

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

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