{"id":50516926,"url":"https://github.com/luminik-io/alfred-os","last_synced_at":"2026-06-18T02:01:01.329Z","repository":{"id":357411071,"uuid":"1224859808","full_name":"luminik-io/alfred-os","owner":"luminik-io","description":"Local agent OS for solo builders: launchd-managed Claude Code/Codex fleets, git-worktree isolation, Slack reporting, safety gates, and reproducible setup.","archived":false,"fork":false,"pushed_at":"2026-06-13T18:44:52.000Z","size":7017,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-13T20:22:18.721Z","etag":null,"topics":["agent-orchestration","agentic-engineering","ai-agents","automation","claude-code","codex","developer-tools","git-worktrees","launchd","macos","slack","solo-builder"],"latest_commit_sha":null,"homepage":"https://alfred.luminik.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luminik-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-29T17:47:34.000Z","updated_at":"2026-06-13T18:44:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/luminik-io/alfred-os","commit_stats":null,"previous_names":["luminik-io/alfred-os"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/luminik-io/alfred-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminik-io%2Falfred-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminik-io%2Falfred-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminik-io%2Falfred-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminik-io%2Falfred-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luminik-io","download_url":"https://codeload.github.com/luminik-io/alfred-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luminik-io%2Falfred-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34472826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","agentic-engineering","ai-agents","automation","claude-code","codex","developer-tools","git-worktrees","launchd","macos","slack","solo-builder"],"created_at":"2026-06-03T01:00:29.043Z","updated_at":"2026-06-18T02:01:01.319Z","avatar_url":"https://github.com/luminik-io.png","language":"Python","funding_links":[],"categories":["Tools","Applications"],"sub_categories":["Development Tools","Autonomous Agent Task Solver Projects"],"readme":"# Alfred\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/brand/alfred-logo-transparent.png\" alt=\"Alfred logo\" width=\"180\"\u003e\n\u003c/p\u003e\n\n[![CI](https://github.com/luminik-io/alfred-os/actions/workflows/ci.yml/badge.svg)](https://github.com/luminik-io/alfred-os/actions/workflows/ci.yml)\n[![Site](https://github.com/luminik-io/alfred-os/actions/workflows/site.yml/badge.svg)](https://alfred.luminik.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![macOS](https://img.shields.io/badge/macOS-13%2B-black?logo=apple)\n![Linux](https://img.shields.io/badge/Linux-Debian%2FUbuntu-A81D33?logo=debian\u0026logoColor=white)\n![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python\u0026logoColor=white)\n\n**An autonomous engineering team that ships while you are away.**\n\nAlfred plans across your repos or monorepo packages, implements with the\nClaude Code and Codex subscriptions you already pay for, and reports to\nSlack while you focus on something else. Drake turns your plans into tasks.\nLucius writes the code and opens pull requests. Ra's al Ghul reviews them.\nBatman coordinates work that spans many repos. The agents run on the\nsubscriptions you already pay for, on a computer you control. No provider API\nkeys, no cloud agent service.\n\nDocs site: https://alfred.luminik.io\n\n## Why use it\n\nInteractive coding agents finish one prompt while you sit at the keyboard.\nAlfred is the layer around them for work that keeps coming back and that you\nwant shipped without you. It picks up tasks from GitHub, gives each run its own\nisolated copy of the repo, sends the right work to the right agent, hands\nfinished code to a reviewer, caps how much it can spend, and keeps several\nagents from stepping on each other.\n\n- Narrow roles, not a chatty multi-agent crowd: Drake plans, Lucius\n  implements, Ra's al Ghul reviews, Bane adds tests, Nightwing picks up\n  unresolved review comments, Batman drafts multi-repo rollouts.\n- Coordinate through ordinary repo primitives: GitHub issues and pull\n  requests, labels, specs, isolated git worktrees, commit trailers, and Slack\n  summaries. The local dashboard and desktop app inspect those same sources;\n  they do not become a hosted control plane.\n- Treat Slack as the planning surface: teammates can reply in a Batman plan\n  thread with scope changes, questions, and acceptance criteria while the\n  operator keeps approval authority. Registered plan-thread replies persist\n  local revision artifacts and echo the current repo scope before approval.\n  Follow-up replies after PR links are captured as context for the next pass,\n  not as implicit merge approval.\n- Run the fleet conversationally from Slack: trusted control commands\n  (`status`, `runs`, `plans`, `plan \u003cid\u003e`, `draft \u003cid\u003e`, `handled \u003cid\u003e`,\n  `memory` / `memories`, `memory remember ...`, `memory harvest`, `remember ...`,\n  `memory promote \u003cid\u003e`, `memory reject \u003cid\u003e`, `memory redis`, `memory sync`,\n  `pause`, `resume`) inspect and steer local state from chat with no shell. Scoped Slack\n  drafts and scheduled failure harvests can queue reviewable memory candidates\n  without promoting them. An approved draft can cross the off-by-default bridge into a labeled issue, and in-thread\n  progress posts (claimed, PR opened, CI, merged) report back as the fleet\n  works it. A plain-language intake profile lets a non-technical user approve\n  outcomes instead of code.\n- Route engines by role. Run implementation on Claude Code and review on\n  Codex, or keep Claude as primary with Codex fallback for selected agents.\n- Bring your own subscription. Alfred shells out to your local `claude` and\n  optional `codex` CLI auth. It does not bill LLM calls separately and does\n  not require provider API keys.\n- Keep autonomy bounded: one firing, one worktree, one IAM scope, one Slack\n  report, hard spend caps, and an explicit GitHub state machine. A planned\n  single-repo issue lands behind an operator-approval gate\n  (`agent:plan-pending-approval`) and is held from autonomous pickup until you\n  approve it.\n\nDefault flow: specs or roadmap context -\u003e Drake files scoped\n`agent:implement` issues -\u003e Lucius claims one issue and opens a worktree -\u003e\nClaude Code or Codex implements -\u003e a PR opens with `agent:authored` -\u003e Ra's al\nGhul reviews -\u003e Nightwing fixes P0/P1 comments -\u003e Bane adds tests -\u003e Slack\nreports what changed.\n\n## Quick start\n\nTwo ways in. The dry-run needs nothing installed and shows you the whole\nfiring lifecycle; the full install wires up a real scheduled fleet.\n\n### Try it in 2 minutes (dry-run)\n\nWant to watch an agent fire before configuring anything? Dry-run mode runs the\nwhole firing lifecycle (pick, claim, worktree, invoke, act, release, report)\nwith every side-effecting boundary stubbed. No LLM call, no spend, no Slack\npost, no GitHub mutation, no real repo. It works with **zero host config**: no\n`gh` auth, no AWS, no Slack, no Claude.\n\n```sh\ngit clone https://github.com/luminik-io/alfred-os.git ~/code/alfred-os\ncd ~/code/alfred-os\nPYTHONPATH=lib python3 examples/bin/echo_summarise.py --dry-run\n```\n\nYou get a narrated, step-numbered trace of the full lifecycle and an exit code\nof 0:\n\n```text\n[dry-run]  1. (start) echo dry-run firing, no LLM, no spend, no gh/slack/git side effects\n[ECHO-PREFLIGHT-FAILED] 2 issue(s):\n  - env var `ECHO_REPO_SLUG` is unset\n  - env var `GH_ORG` is unset\n[dry-run]  2. (preflight) preflight reported config gaps, continuing (dry-run)\n[dry-run]  3. (pick) would `gh issue list --label agent:summarise`; using a synthetic issue instead\n[dry-run]  4. (gh) would claim dry-run-org/dry-run-repo#0 for echo (firing_id=...): add agent:in-flight, post claim comment\n[dry-run]  5. (llm) would invoke claude with prompt of 463 chars, model=(cli-default), max_turns=5\n[dry-run]  6. (spend) would increment real ledger (firings_today+=1, turns_today+=3, cost_usd_today+=0.0); dry-run ledger only\n[dry-run]  7. (gh) would `gh issue comment #0` on dry-run-org/dry-run-repo: **Echo (auto-summary):** [dry-run] synthetic claude result, no LLM was invoked. ...\n[dry-run]  8. (gh) would release dry-run-org/dry-run-repo#0 for echo (firing_id=...): outcome=success, remove agent:in-flight, add agent:done\n[dry-run]  9. (spend) would set real ledger (consecutive_failures=0); dry-run ledger only\n[dry-run] 10. (spend) would increment real ledger (successes_today+=1); dry-run ledger only\n[dry-run] 11. (slack) would post to Slack (severity=info): Echo summarised dry-run-org/dry-run-repo#0: ...\n```\n\nThe same works for `examples/bin/hello.py` and `bin/lucius.py`, and via the\n`ALFRED_DRY_RUN=1` env var instead of the flag. See [`docs/DRY_RUN.md`](docs/DRY_RUN.md)\nfor what is stubbed versus real.\n\nAfter install, the operator CLI resolves every codename without touching the\nhost scheduler:\n\n```sh\nalfred dry-run lucius\nalfred dry-run drake\nalfred dry-run all\n```\n\n### Full install\n\nAbout 30 minutes from a fresh Mac or Debian/Ubuntu host.\n\nSource checkout path:\n\n```sh\ngit clone https://github.com/luminik-io/alfred-os.git ~/code/alfred-os\ncd ~/code/alfred-os\nbash install.sh\nexec $SHELL                       # pick up ~/.alfredrc\ngh auth login                     # GitHub\nclaude                            # Claude Code first-run auth\n./bin/alfred-init.py              # choose agents, repos, codenames, Slack\n```\n\nmacOS Homebrew path, if you prefer package-manager installs:\n\n```sh\nbrew tap luminik-io/alfred-os https://github.com/luminik-io/alfred-os\nbrew install alfred-os\nalfred-install\nexec $SHELL                       # pick up ~/.alfredrc\ngh auth login                     # GitHub\nclaude                            # Claude Code first-run auth\nalfred-init                       # choose agents, repos, codenames, Slack\n```\n\nThe Homebrew formula installs the latest tagged release and exposes\n`alfred`, `alfred-init`, `alfred-install`, `alfred-deploy`, and\n`alfred-doctor` on your PATH. Use the source checkout path when you want to\nwork from `main` or run the Linux installer.\n\nFor a solo-builder setup that an AI coding tool can run without guessing at\nprompts or labels, pass one repo or an explicit comma-separated repo list:\n\n```sh\n./bin/alfred-init.py \\\n  --non-interactive \\\n  --agents starter \\\n  --repos your-org/api,your-org/web \\\n  --slack-webhook skip\n```\n\nThe starter fleet is Drake, Lucius, Ra's al Ghul, and agent-cleanup: plan\nissues, implement labelled issues, review PRs, and clean stale state. Slack is\noptional. The `--repos` owner must match `GH_ORG`; the runtime agents store the\nbare repo name in `~/.alfredrc` and build `GH_ORG/repo` at firing time.\n`alfred-init.py` now seeds prompt templates into\n`~/.alfred/prompts/`, creates the standard GitHub labels on selected repos,\nwrites `launchd/agents.conf` (the shared scheduler manifest), updates\n`~/.alfredrc`, runs deploy, and runs\ndoctor.\n\nFor a framework-only install with no agents configured, use `bash deploy.sh \u0026\u0026\nbash bin/doctor.sh`; doctor reports `0 passed, 0 failed`. See\n[`examples/bin/echo_summarise.py`](examples/bin/echo_summarise.py) for the\nsmallest useful agent (the one [the tutorial](docs/TUTORIAL.md) builds) or\n[`examples/bin/hello.py`](examples/bin/hello.py) for the absolute minimum.\n\nFull setup including AWS IAM-per-agent, Slack webhook, and your first scheduled firing: [`BOOTSTRAP.md`](BOOTSTRAP.md). From-zero install with troubleshooting: [`INSTALL.md`](INSTALL.md). On Linux, see [`docs/LINUX.md`](docs/LINUX.md) for the `systemd --user` path.\n\nWant Claude Code, Codex, or another local coding assistant to drive setup for\nyou? Use [`docs/AI_ASSISTED_INSTALL.md`](docs/AI_ASSISTED_INSTALL.md). It gives\nthe assistant a copy-paste prompt, explicit repo-scope lanes, and the guardrails\nthat prevent it from assigning every repo or inventing secrets. For checkout\nlayout choices, use [`docs/WORKSPACE_PATTERNS.md`](docs/WORKSPACE_PATTERNS.md).\n\n## System shape\n\n```mermaid\nflowchart LR\n    issue[\"GitHub issue or PR\"] --\u003e schedule[\"host scheduler or manual firing\"]\n    schedule --\u003e runner[\"bin/role.py\"]\n    runner --\u003e shared[\"lib/agent_runner/\"]\n    shared --\u003e lock[\"lock, preflight, spend caps\"]\n    shared --\u003e worktree[\"isolated git worktree\"]\n    shared --\u003e engine{\"engine\"}\n    engine --\u003e claude[\"Claude Code CLI\"]\n    engine --\u003e codex[\"Codex CLI\"]\n    shared --\u003e github[\"GitHub issues, branches, PRs\"]\n    shared --\u003e slack[\"Slack webhook or bot token\"]\n    shared --\u003e state[\"ALFRED_HOME state\"]\n```\n\nOne firing is one short-lived process. The OS scheduler owns cadence, the\nrunner owns safety rails, and the LLM CLI only receives the bounded task.\n\n## Design notes\n\nMost 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:\n\n- Long-running loops have no failure isolation. One bad run trashes the others.\n- In-memory state can't survive an OS reboot. A long-lived host restarts every few weeks.\n- Chat-first interfaces put the operator on the critical path.\n\nAlfred inverts that. The host scheduler fires `bin/\u003crole\u003e.py` every N minutes, the `agent_runner` module wraps each firing in a lock, preflight, spend cap, and isolated worktree, and `claude -p` (or `codex exec`) does the bounded LLM work in a fresh subprocess. Spend is tracked per agent per day. When a Claude-backed agent hits a Claude provider limit, every other agent skips for an hour. The framework code never touches the LLM directly: the runner is plain Python, the model writes the code. The [System shape](#system-shape) diagram above traces one firing end to end; [`ARCHITECTURE.md`](ARCHITECTURE.md) has the full rationale.\n\n## Runtime boundary\n\nAlfred core does not install or run an external agent gateway, memory database,\nskill registry, or dashboard service. The fleet works with local Python scripts,\n`gh`, `git`, and the configured LLM CLIs.\n\n`ALFRED_HOME` is the runtime root. A fresh install defaults to `~/.alfred`,\nwhere deployed scripts, state, logs, Codex artifacts, prompt overrides, and\nworktrees live. Alfred uses `ALFRED_HOME` only for its runtime path.\n\nCompanion layers can be useful around Alfred, but they are not bundled and must\nnot be required for a clean OSS install. See\n[`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) for the boundary.\n\nAlfred is also not a hosted model gateway. It owns the repeatable local fleet pattern: schedules, worktrees, issue claims, PR loops, Slack reporting, and failure guards. Today Alfred supports Claude Code CLI and Codex CLI adapters. Other engines require a wrapper binary or new adapter code.\n\n## Anonymous usage telemetry (opt-in)\n\nAlfred ships a small, **opt-in, off-by-default** telemetry reporter. It exists\nfor one purpose: a public \"Alfred has opened N pull requests and merged M across\nK installs\" proof counter. It is off until you turn it on, and one environment\nvariable turns it off again.\n\n**Default state: OFF.** Nothing is sent, no `install_id` is generated, and no\nnetwork call is made unless you set `ALFRED_TELEMETRY_ENABLED=1`. Any other\nvalue (including a typo like `true`) leaves it off. There is exactly one way to\nenable it and removing that one variable disables it completely.\n\n**Exactly what is sent**, once a day when enabled, to the endpoint you set in\n`ALFRED_TELEMETRY_URL`:\n\n```json\n{\n  \"install_id\": \"a-random-opaque-token\",\n  \"period\": \"lifetime\",\n  \"prs_opened\": 42,\n  \"prs_merged\": 31,\n  \"prs_reviewed\": 18,\n  \"loc_added\": 12873\n}\n```\n\n- `install_id` is a random token generated locally on first opt-in. It is not\n  derived from your hostname, MAC, user, or email. It lets the server\n  de-duplicate re-sends and count distinct installs, nothing more.\n- The four numbers are anonymous, cumulative lifetime counts from your local\n  fleet-brain, sent into one stable `period` bucket so daily re-sends never\n  double count.\n- `loc_added` is a file-delta count (one per repo file an agent touched); the\n  brain does not store per-line LOC. See [`docs/TELEMETRY.md`](docs/TELEMETRY.md).\n\n**What is never sent:** repo names, file paths, code, commit text, branch names,\nhostnames, IP addresses, Slack handles, codenames, or anything that identifies a\nperson or machine. The reporter is fail-soft: a network error never breaks a\nfiring.\n\n**To enable:** set both variables in `~/.alfredrc` and uncomment the\n`proof-telemetry` line in `launchd/agents.conf`:\n\n```sh\nALFRED_TELEMETRY_ENABLED=1\nALFRED_TELEMETRY_URL=https://your-worker.example.com/ingest\n```\n\n**To disable:** remove `ALFRED_TELEMETRY_ENABLED` (or set it to anything but\n`1`). The reporter immediately becomes a no-op.\n\n**To see exactly what would be sent before opting in:**\n`ALFRED_TELEMETRY_ENABLED=1 python3 bin/proof-telemetry.py --dry-run` prints the\npayload and sends nothing.\n\nYou run your own collector. The server half is a self-hostable Cloudflare Worker\nunder [`telemetry/worker/`](telemetry/worker/); Alfred does not phone home to any\nLuminik-operated endpoint. The collector takes an optional `INGEST_TOKEN` so only\nyour own opted-in hosts can write to the counter; `/ingest` has no browser CORS\nand a per-IP rate limit either way. Full contract:\n[`docs/TELEMETRY.md`](docs/TELEMETRY.md).\n\n## What's in here\n\n| Path | What it is |\n|---|---|\n| [`lib/agent_runner/`](lib/agent_runner/__init__.py) | Shared library (package; public API re-exported from `__init__.py`). Preflight, lock, spend, claude_invoke, codex_invoke, gh, slack, event-log, commit-trailer, handoff-table, issue claim state machine, runner gate helpers, dedup helpers (`find_open_authored_pr_for_issue`, `reuse_or_make_worktree`), worktree recovery refs, runtime memory, slack severity routing, dry-run seam. |\n| [`lib/slack_format.py`](lib/slack_format.py) | Block Kit + bot-token Slack helpers: per-firing `firing_thread_root` / `firing_thread_reply` / `firing_thread_close`. Severity colour stripes. |\n| [`lib/batman.py`](lib/batman.py) | Bundle primitives for the multi-repo coordinator: `Bundle`, `claim_bundle` (all-or-nothing), `release_bundle`, `parse_plan_from_bundle`. |\n| [`lib/planning_assistant.py`](lib/planning_assistant.py) | Shared issue/spec refinement helpers for `alfred serve`, `alfred spec refine`, and Slack plan amendments. |\n| [`lib/scheduler.py`](lib/scheduler.py) | Host-scheduler abstraction: `launchd` on macOS, `systemd --user` on Linux, behind one interface. |\n| [`bin/alfred`](bin/alfred) | Operator CLI: `alfred agents`, `alfred status`, `alfred enable \u003ccodename\u003e`, `alfred disable \u003ccodename\u003e`, `alfred pause` / `resume` / `run`, `alfred clear-lock`, `alfred brain ...`, `alfred mcp serve`, `alfred spec ...`, `alfred labels bootstrap/check`, `alfred engine status/set`, `alfred claude status/primary/secondary/swap/probe`, `alfred codex status/probe`, `alfred auth status/probe`. |\n| [`bin/alfred-usage.py`](bin/alfred-usage.py) | Live Claude + Codex subscription usage for the rolling 5-hour and weekly limit windows, read from the engines' own local CLI state (no billing API). The same data is served over the live `GET /api/usage` endpoint; this is its `alfred usage` CLI front end. |\n| [`bin/alfred-shipped-summary.py`](bin/alfred-shipped-summary.py) | Daily/weekly shipped-work report across configured repos: merged PRs, issues, LOC, and model/config changes. Also available as `alfred shipped`. |\n| [`bin/shipped-summary-daily.sh`](bin/shipped-summary-daily.sh), [`bin/shipped-summary-weekly.sh`](bin/shipped-summary-weekly.sh) | Launchd wrappers for scheduled shipped-work Slack reports. |\n| [`bin/batman.py`](bin/batman.py) | Multi-repo coordinator. Picks `agent:large-feature` / `agent:bundle:\u003cslug\u003e` issues, posts a Slack plan, applies approved repo-scope amendments, and carries approved thread notes into child issues. |\n| [`bin/fleet-doctor.py`](bin/fleet-doctor.py) | Daily fleet-health snapshot. Read-only checks (paused repos, global block, stale worktrees, runner gate list) → severity-stripe Slack thread. |\n| [`bin/memory-harvest.py`](bin/memory-harvest.py) | Optional scheduled memory-harvest wrapper. Queues reviewable repeated-failure candidates and nudges Slack when there is something to review. |\n| [`bin/proof-telemetry.py`](bin/proof-telemetry.py) | Opt-in, off-by-default anonymous proof-telemetry reporter. Hard no-op unless `ALFRED_TELEMETRY_ENABLED=1`. Posts only aggregate counts (PRs opened/merged/reviewed, file deltas) to your configured endpoint; fail-soft. |\n| [`telemetry/worker/`](telemetry/worker/) | Self-hostable Cloudflare Worker that ingests the anonymous aggregate and serves the public totals for the site counter. Ships with placeholder ids; deploy under your own account. |\n| [`bin/`](bin/) | Operator helpers, including `doctor.sh` (host validator). |\n| [`launchd/`](launchd/) | `_template.plist` + `agents.conf.example` + `render.sh` (TSV → plists). |\n| [`systemd/`](systemd/) | `_template.service` + `_template.timer` + `render.sh` (TSV → `systemd --user` units) for the Linux path. |\n| [`deploy.sh`](deploy.sh) | Sync `lib/` + `bin/` into `${ALFRED_HOME}`. If `launchd/agents.conf` exists, render units and bootstrap the host scheduler; otherwise do a framework-only deploy. |\n| [`install.sh`](install.sh) | Fresh-machine bootstrap: Homebrew (macOS) or apt (Debian/Ubuntu) + npm + dirs + shell rc. Idempotent. |\n| [`examples/bin/hello.py`](examples/bin/hello.py) | Smallest possible codename agent: preflight + Slack post. |\n| [`examples/bin/echo_summarise.py`](examples/bin/echo_summarise.py) | Full lifecycle reference: pick / claim / claude / act / release / report. |\n| [`examples/bin/label_state.py`](examples/bin/label_state.py) | Operator CLI for the issue claim state machine. |\n| [`examples/git-hooks/pre-push`](examples/git-hooks/pre-push) | Refuses push if a referenced issue is in-flight. Symmetric guard. |\n| [`Formula/alfred-os.rb`](Formula/alfred-os.rb) | Homebrew formula pinned to the latest public release tarball. |\n| [`site/`](site/) | Astro Starlight docs site, with GitHub Pages publishing gated by the release repo variable. |\n| [`clients/desktop/`](clients/desktop/) | Tauri Mac/Linux client. A local dashboard over `alfred serve` JSON APIs, with in-app Plans, Memory, Fleet, and Logs inspectors plus explicit Slack and GitHub external links. Home carries a Claude + Codex usage rail (real subscription usage, no billing API; backed by the live `GET /api/usage` endpoint); Fleet defaults to a cinematic agent roster with a list toggle. Builds native installers (`.app`/`.dmg`, `.AppImage`/`.deb`) from the Tauri bundle config. |\n| [`lib/slack_control.py`](lib/slack_control.py), [`lib/slack_trust.py`](lib/slack_trust.py) | Trusted Slack control/query commands (`status`/`runs`/`plans`/`plan`/`draft`/`handled`/`memory`/`remember`/`pause`/`resume`/`trusted`/`trust`/`untrust`/`help`), codename-, plan-id-, and memory-id-validated, no shell, with local collaborator state under `$ALFRED_HOME/state/slack-trust`. |\n| [`lib/slack_thread_status.py`](lib/slack_thread_status.py), [`bin/alfred-slack-thread-sync.py`](bin/alfred-slack-thread-sync.py) | In-thread fleet progress: read-only issue/PR/CI sweep that posts only the new lifecycle states back to the originating Slack thread. |\n\n## Documentation\n\n- [Install](INSTALL.md): fresh-machine walkthrough.\n- [Install tiers](docs/INSTALL_TIERS.md): `core` (standalone, headless), optional `client` (desktop), optional `slack`.\n- [AI-assisted install](docs/AI_ASSISTED_INSTALL.md): copy-paste prompt for Claude Code, Codex, or another local coding assistant.\n- [Workspace patterns](docs/WORKSPACE_PATTERNS.md): one-repo, multi-repo, specs-led, and Batman planning layouts.\n- [Specs-driven development](docs/SPECS_DRIVEN_DEVELOPMENT.md): how to turn specs into issue queues, Batman plans, and reviewable PRs.\n- [Bootstrap](BOOTSTRAP.md): operations guide (AWS IAM, Slack, troubleshooting).\n- [Tutorial: your first agent](docs/TUTORIAL.md): Echo, end-to-end.\n- [Dry-run mode](docs/DRY_RUN.md): watch a full firing lifecycle with no LLM call, no spend, and no side effects.\n- [Architecture](ARCHITECTURE.md): design rationale.\n- [Architecture diagrams](docs/ARCHITECTURE.md): mermaid diagrams for the agent lifecycle, model dispatch, locking, the Slack-native flow, the disk guardian, and the layered install.\n- [State machine](docs/STATE_MACHINE.md): `agent:in-flight` → `agent:pr-open` → `agent:done` lifecycle.\n- [Fleet brain](docs/FLEET_BRAIN.md): local memory, Slack-driven reviewable lesson candidates, failure history, reliability governor, explicit Redis AMS sync, and read-only MCP access.\n- [Native local client](docs/NATIVE_CLIENT.md): Mac/Linux client, Slack-native boundary, the usage capacity rail (backed by the live `GET /api/usage` endpoint), cinematic agent roster, and local API shape.\n- [Desktop client](docs/DESKTOP_CLIENT.md): the desktop client tab by tab, the Claude + Codex usage rail (backed by the live `GET /api/usage` endpoint), the `alfred serve` seam, and building native installers.\n- [Operator analytics CLIs](docs/CLI.md): `alfred metrics`, `alfred logs`, `alfred usage`, and `alfred slack-listener`.\n- [Goals](docs/GOALS.md): durable goal contract across Slack, CLI, client, planning readiness, evaluator, and memory.\n- [Plain mode](docs/PLAIN_MODE.md): the non-technical intake profile (`ALFRED_INTAKE_PROFILE=plain`).\n- [Claude Code and Codex](docs/CLAUDE_CODE.md): install, Pro vs Max, account routing, engine routing.\n- [Codex provider](docs/CODEX_PROVIDER.md): Codex engine modes, probe commands, runtime contract, and billing posture.\n- [Slack setup](docs/SLACK_SETUP.md): webhook + AWS storage + (optional) bot token, planning listener, trusted control commands, the off-by-default issue bridge, and in-thread fleet-progress thread-sync.\n- [AWS setup](docs/AWS_SETUP.md): IAM-per-agent, scoped policies.\n- [Skills](docs/SKILLS.md): recommended Claude Code skills.\n- [Telemetry](docs/TELEMETRY.md): the opt-in, off-by-default anonymous proof-counter. Exactly what is sent, what is never sent, the single on/off switch, and how to self-host the collector.\n- [Integrations](docs/INTEGRATIONS.md): optional companion tools and what Alfred does not bundle.\n- [Hermes integration](docs/HERMES.md): optional operator-layer recipe for teams already using Hermes.\n- [Linux](docs/LINUX.md): Debian/Ubuntu via `systemd --user` timers. Install, deploy, and operate.\n- [Publishing](docs/PUBLISHING.md): GitHub Pages, custom-domain, and release-site checks.\n- [Contributing](CONTRIBUTING.md) | [Roadmap](ROADMAP.md) | [Changelog](CHANGELOG.md)\n- [Security](SECURITY.md): private-disclosure process.\n- [Release checklist](docs/RELEASE_CHECKLIST.md): pre-tag gates, scrub scan, GitHub Release flow.\n\nRendered version: https://alfred.luminik.io/.\n\n## Codename pattern\n\nThe framework expects one agent script per narrow specialist, named after a coherent fictional cast, coordinating via labels and gh state rather than in-process calls. The shipped examples use Batman side-characters: **Batman** (multi-repo coordinator), **Lucius** (feature dev), **Drake** (planner), **Bane** (test coverage), **Ra's al Ghul** (PR review), **Robin** (bug triage), **Nightwing** (review-fix), **Huntress** (post-deploy smoke), **Gordon** (deploy health). Pick whatever cast fits.\n\nThe cast matters for two reasons. Codenames appear in PR titles, Slack messages, and commit-trailer metadata; a coherent cast makes the fleet's channel scannable. And narrow scopes per codename are a forcing function for design quality. \"What does Bane do?\" is a sharper question than \"what does the test agent do?\".\n\nSee [Architecture → Codename pattern](https://alfred.luminik.io/concepts/codename-pattern/) for more.\n\n## Design boundaries\n\nAlfred has a deliberate shape. These are not missing features; they are the design.\n\n- **Single operator.** One person, one host, one config. Alfred is not multi-tenant and will not become a hosted SaaS. It is software you install and run yourself.\n- **The OS schedules; Alfred runs.** No long-running orchestration loop. `launchd` / `systemd` own cadence; each firing is a fresh, isolated process. That means better failure isolation, and it survives reboots.\n- **Local CLIs, not a model gateway.** Alfred shells out to `claude` and optional `codex` on your own subscription-backed CLI auth. It does not run a hosted inference service and does not require provider API keys.\n- **Explicit goals, not runaway autonomy.** Larger work should have an operator-owned contract: outcome, verification, constraints, human gates, and blocked condition.\n- **Lean on the platform.** When Anthropic ships a capability natively (Agent Teams, the Memory Tool), Alfred adopts it rather than re-implementing it.\n- **Browser automation is per-codename.** If a codename needs a browser, it installs Playwright in its own bin script; the core stays lean.\n\nThe engineering fleet ships today. The local memory layer, reliability\ngovernor, `alfred serve`, and the first Mac/Linux client also ship today;\ncontent, sales, and ops departments are the next larger surface area:\n[`ROADMAP.md`](ROADMAP.md).\n\n## Status\n\n**Latest release: v0.5.1.** Alfred ships a local engineering-agent team for solo\nbuilders: install, starter setup, prompt seeding, GitHub label setup, specs-led\nworkspace patterns, doctor, dry-run, Linux/systemd or macOS launchd scheduling,\nClaude/Codex engine routing, Slack reporting, and isolated worktree execution.\nv0.5.1 carries the first signed native Mac and Linux desktop app (built with Tauri),\nlive Claude and Codex subscription usage in that app, a single-repo\noperator-approval gate, a disk guardian that pauses your agents cleanly when the\ndisk is nearly full, a Slack planning path that turns an approved draft into a\nlabeled GitHub issue, fleet-brain reliability and memory tooling, one-command\nsetup-token bootstrap, a public download page, and SEO plus consent-gated\nanalytics on the site. See\n[CHANGELOG.md](CHANGELOG.md) and [ROADMAP.md](ROADMAP.md) for the full ledger.\n\nThe native app has Inbox, Ask, Work, Agents, and Setup surfaces\nfor local trust and repair. Its Inbox view carries a Claude and Codex usage rail\n(real subscription usage, read from the engines' own local CLI state with no\nbilling API, backed by the live `GET /api/usage` endpoint, with the same data\nalso available from the `alfred usage` CLI). Its Agents view has a cinematic\nroster with a list toggle. Runs emit step-level events so the timeline shows\nreal progress, and any\nissue carrying the operator-approval gate label (`agent:plan-pending-approval`)\nis held from autonomous pickup until the operator approves it and the label\nclears. Slack remains the primary collaboration surface.\n\nThe design boundary is stable: one operator, one local host, local CLIs, isolated worktrees, GitHub as the coordination layer. PRs are welcome when they strengthen that shape: reliability, setup, docs, tests, new codenames with clear scope, or optional integrations that fail cleanly. Bigger shifts, such as a new department or runtime change, should start as a discussion.\n\n## License\n\nMIT. See [`LICENSE`](LICENSE). Copyright (c) 2026 DataRavel Inc.\n\n## Why the repo slug is `alfred-os`\n\nAlfred is named after Bruce Wayne's butler, the one who keeps the cave running while the mission is in flight. The default codenames are bat-themed, and the framework that lets the cave function is `alfred-os`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluminik-io%2Falfred-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluminik-io%2Falfred-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluminik-io%2Falfred-os/lists"}