macOS Service¶
After creating your configuration, install or upgrade the background service:
This installs ~/Applications/Aesop Agentic.app and registers it with Launch
Services. Opening the app follows ui_mode; select Browser for an installation without the Tauri component.
terminal_app selects Terminal, iTerm2, or Warp when using the terminal interface. The LaunchAgent
uses a launcher named Aesop Agentic and associates it with the app bundle.
The app name, executable name, and notification title are Aesop Agentic;
package authorship and app information credit Colin Conwell.
Installation compiles a small native launcher using Apple's Command Line Tools
(xcode-select --install if needed). It stays alive while its Python child runs,
forwards termination signals, and returns the child's exit status. The native
bundle gives macOS privacy requests an app identity; the previous shell launcher
replaced itself with Python and could appear as python3.14.
The stable bundle and launchd identifier remains com.colinconwell.aesop-agentic.
Machine identifiers stay unchanged during upgrades to avoid duplicate jobs.
The service checks at login and every 15 minutes; it collects only when due.
aesop service run-now requests a schedule check and leaves an active run alone.
The bundle is a local launcher, so keep its Python environment and checkout in
place. Rerun service install after moving either, switching environments, or
changing configuration paths or the check interval. The installer captures the
absolute config path, including when using aesop --config /path/config.toml
service install. It refuses to interrupt an active collection and restores
previous installation files and a previously loaded job if an upgrade fails.
To remove the service and its managed app, run aesop service uninstall.
Configuration, archives, browser profiles, and logs are retained.
App Name Versus Verified Developer¶
The local launcher is ad hoc signed. Its bundle and native executable use
Aesop Agentic. Files & Folders grants made to the old Python executable are
separate from this app's grants and may remain visible. Do not remove shared
Python permissions merely to tidy the list. Newly requested access should be
attributed to Aesop Agentic when launched through its app or installed service.
Direct python -m aesop_agentic / aesop invocations run under their terminal's
launch context and do not use the installed native launcher.
To check source access through the app without collecting or backing up files:
Review any macOS access prompts, then look under Privacy & Security → Files & Folders. Apple describes why bundled privacy clients need a native main executable in On File System Permissions. Ad hoc signatures do not guarantee that grants survive executable changes; macOS may request permission again after an upgrade.
A verified developer name in System Settings comes from an Apple-issued signing identity. Setting author metadata to “Colin Conwell” does not create that identity; an ad hoc installation may still show “unidentified developer.” A signed distribution requires an appropriate Developer ID certificate and a matching signed app/helper. See Apple’s background item attribution documentation.
Check aesop service status for the loaded executable and sfltool dumpbtm for
macOS background-item attribution. Do not reset the system-wide background-item
database to rename one service.
Archive Icon¶
The approved Archive mark uses a vertical cyan, blue, violet, and magenta gradient.
the package’s assets/branding/ directory contains light and dark PNGs, separate ICNS files,
the editable AesopAgentic.icon document, and the compiled Assets.car.
Both the collector app and its nested desktop bundle declare CFBundleIconName for appearance-aware rendering on macOS 26+
and includes Apple's generated ICNS fallback for older versions. The system
controls which rendition each surface displays.
The artwork was generated with the built-in image generator; references and
prompts are preserved in PROMPTS.json. To rebuild the packaged assets after
editing the Icon Composer document, run python scripts/build_icons.py on a Mac
with Xcode 26 or newer at /Applications/Xcode.app. End-user installation uses
the compiled assets and does not require Icon Composer.
Native Notifications¶
Archive notifications use Apple's UserNotifications framework inside the installed Aesop Agentic app. macOS supplies the app name and Archive icon, along with standard banner, Notification Center, Focus, sound, and preview controls. The previous AppleScript notification route is no longer used.
After installing or upgrading the service:
aesop notifications enable # Request one-time macOS authorization
aesop notifications status # Read authorization, alert, and sound settings
aesop notifications test # Send a preview without collecting anything
Routine Archive Updated notifications, including known readable-coverage gaps, are silent. Archive Needs Attention
and Archive Failed notifications for source errors, parser errors, or backup failures request the system sound, subject to your
notification settings. Messages contain short counts and summaries; detailed
exceptions and paths stay in the logs. Open aesop dashboard for run details.
Scheduled updates replace the previous archive-status notification instead of
accumulating one per run. The preview has its own notification identifier.
Authorization is requested only by notifications enable. Background collection
does not prompt for access. A denied permission, unavailable app, or notification
timeout is logged without changing the collection result. If access was denied,
enable it under System Settings → Notifications → Aesop Agentic. To stop the
collector sending notifications, set notify = false in the configuration.
The native implementation follows Apple's guidance for notification authorization and local notification delivery.