Skip to content
Alfred-OS

Alfred-OS

A framework for launchd-managed Claude Code agents on a single Mac.
Install (30 min) View on GitHub

Design notes

Section titled “Design notes”

Most agent frameworks (crewAI, MetaGPT, OpenHands, AutoGPT-style loops) assume one long-running Python process, in-memory state, and a human at a REPL. Wrong shape for unattended work.

  • Long-running loops have no failure isolation. One bad run trashes the others.
  • In-memory state can’t survive an OS reboot. macOS restarts every few weeks.
  • Chat-first interfaces put the operator on the critical path.

Alfred-OS’s shape: each agent is a fresh subprocess in its own git worktree, dispatched by launchd, isolated by per-agent IAM, bounded by per-day spend caps with a fleet-wide rate-limit poison pill.

HERMES_HOME is the runtime-root name inherited from the original internal Alfred/Hermes fleet. alfred-os core does not install or run a Hermes agent process. Hermes skills, MCP, gbrain, canon, and dashboarding remain compatible optional integrations.

launchd plist (every N min)
   │
   ▼
${HERMES_HOME}/bin/<role>.py         one stable role runner per agent
   │
   ▼
agent_runner module                  lock + preflight + spend + claude_invoke + gh + slack
   │
   ▼
claude -p '<prompt>' --max-turns N   the LLM work, in a fresh subprocess
   │
   ▼
slack_post('<result>', severity=...) report to the fleet's Slack channel

What you get

Section titled “What you get”

launchd dispatch

Every firing is a launchd event. No long-running process; no in-memory state to lose on reboot. The OS is the orchestrator.

Per-firing git worktree isolation

Each claude -p invocation gets a fresh worktree. No cross-firing pollution; safe to crash mid-run.

Per-agent IAM

Every scheduled agent gets its own scoped IAM identity. The operator’s SSO is never used by scheduled agents.

Fleet-wide rate-limit poison pill

When any agent hits Anthropic’s cap, every other agent silently skips for an hour. No stampede.

Issue claim state machine

agent:in-flight → agent:pr-open → agent:done. Race-resistant cooperative coordination via GitHub labels + structured comments.

Operator overrides

do-not-pickup to manually claim an issue. Repo pause/resume to refactor without racing the fleet.

Out of scope

Section titled “Out of scope”

Multi-tenant

Single operator, one Mac, one config.

Web UI

Slack is the human surface.

Long-running loops

The OS scheduler is the orchestrator.

Hosted model gateway

Engines are local CLI adapters, not a hosted inference service.

Hermes distribution

Hermes integrations are optional; this repo ships the launchd fleet core.

Browser runtimes

If you need Playwright, install it in your codename script.

Vector DBs

A doc-shaped memory layer is your choice, not the framework’s.

Quick start

Section titled “Quick start”
Install in 30 minutes Fresh-Mac setup: install.sh handles brew + npm + dirs + shell rc + auth checks.
Build your first agent The Echo tutorial: pick → claim → invoke → act → release → report. The shape every richer codename inherits.
Read the architecture Why launchd, why worktrees, why per-agent IAM. The design constraints that make alfred-os opinionated.

Status

Section titled “Status”

Alfred-OS is at v0.2.1. It ships a complete local engineering-agent fleet for one operator, with the first public launch cleanup pass applied. The framework substrate (agent_runner) is stable for the operator’s own use; expect rough edges if you fork.

Maintained on weekends. Issues triaged on a best-effort basis. PRs that fit the design constraints get reviewed; PRs that broaden scope get politely declined. Read Contributing before opening.

License: MIT.