AgentiLoop Agent!: a native macOS agent harness that drives apps, code and shell

What AgentiLoop Agent! actually does that a chat window cannot

Most LLM front ends stop at text. AgentiLoop Agent! is built around the opposite assumption: the model should be able to act on the machine it runs on. The README describes an "autonomous task loop" that reads a codebase, fixes a bug, builds an Xcode project, commits the diff, drives any Mac app through the Accessibility API, runs shell commands "as you or as root", and can text results over iMessage. The example prompts in the README are deliberately mundane: build the Xcode project and fix errors, play a playlist in Music, take a photo with Photo Booth, send an iMessage, open Safari and search for flights, refactor a class into smaller files, list today's calendar events.

The audience follows from that list. This is for Mac-based developers and power users who already have API keys and want an agent with real system reach, not for someone who wants a hosted assistant that works the same on every operating system. The README is explicit that it is a "100% native Swift 6.2 / SwiftUI app" with no NPM, no Electron, no subscription and no telemetry, and that every Swift package it depends on was written by the same author. That last sentence is worth pausing on. It means the dependency tree is small and controlled, and it also means the bus factor is one person.

The task loop: goal_state, read-before-edit and context compaction

The mechanism the README spends the most words on is how a task decides it is finished. A task cannot declare itself done until `goal_state` criteria are marked with evidence, and an opt-in critic reviews the diff before completion. This is a deliberate constraint on the model: instead of trusting a final "done" message, the harness requires the agent to attach evidence to each criterion.

The second mechanism is a read-before-edit gate. The README states that `edit_file`, `apply_diff` and `diff_apply` refuse to touch a file the model has not read during the current task, or that changed on disk since the last read, checked with SHA-256. When the gate fires, the refusal auto-reads the file so the next call is the edit, and external file changes are surfaced each turn as diff snippets. That is a sensible design for an agent with write access, and it also means the agent cannot edit a file it has only inferred from a directory listing.

Context handling is the third piece. The README describes a compaction threshold computed as model window minus reserved output minus buffer, driven by real `input_tokens`. Compaction is a provider-side nine-section LLM summary, replacing earlier on-device 4K summaries, and after every compaction the open goal, the plan checklist and the edited files are re-attached. Oversized tool results are spilled to disk at emission and recovered through `restore_tool_result`. A 413 overflow routes through forced compaction with a shorter retry, and `max_tokens` overruns recover by escalating and then continuing. Whether that recovery chain behaves well in practice is not something the README can tell you; it is the part I would watch first.

Installing AgentiLoop Agent! and running a first task

There are two paths. The quick start says to download the latest release from GitHub, drag it to Applications, open it, and pick a provider under Settings with an API key. The build-from-source path starts with a clone. Note that the README's clone URL uses a lowercase `agent` path while the repository is listed as `AgentiLoop/Agent`; if the clone fails, check the casing against the repository page.

git clone https://github.com/AgentiLoop/agent.git
cd Agent

From there the README offers two options. Option A opens `Agent.xcodeproj` in Xcode, sets your Development Team, and builds and runs the `Agent` target, approving the helper when prompted. Option B needs only the Xcode Command Line Tools and no developer account:

./build.sh              # Debug
./build.sh Release      # Release
open "build/DerivedData/Build/Products/Debug/Agent!.app"

The README gives this example of opening the Debug build, and the path shows the app bundle is named `Agent!.app`, exclamation mark included. The same section warns that Option B builds are ad-hoc signed: the Launch Agent and Launch Daemon helpers will not register because SMAppService needs a Team ID, but the LLM loop, all tools, Accessibility, AppleScript, shell and MCP still work. That is the trade-off in plain terms. You get the agent, you lose the background helpers.

The troubleshooting list is short and specific. If `xcode-select` points at the Command Line Tools, run `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`. After pulling changes, a stale DerivedData directory can produce an odd `BUILD FAILED`, fixed with `./build.sh clean && ./build.sh`. The config argument is case-sensitive, so it is `./build.sh` for Debug or `./build.sh Release`. The README also notes that Agent! targets macOS 26, so deployment target or SDK errors usually mean updating macOS and Xcode.

For a first real task, the README's own examples are the safest starting point, because they exercise one capability at a time: ask it to list today's calendar events, or to open Safari and search for something. A coding task such as refactoring a class into smaller files will exercise the read-before-edit gate and the snapshot and rollback path, which is where the interesting failure modes live.

Where AgentiLoop Agent! is the wrong tool

The platform constraint is absolute. The README badges macOS 26.4.1 and Swift 6.2, and the troubleshooting section says Agent! targets macOS 26. If you are on an earlier macOS release, or on Linux, or you want the same agent to run on a build server, this project does not fit. There is no server component described in the repository layout, which lists `Agent/`, `AgentHelper/`, `AgentUser/`, `AgentTests/`, `Shared/`, `Agent.xcodeproj/`, `build.sh`, `docs/` and the README translations.

The second boundary is the helper situation. On a build without a Team ID, the Launch Agent and Launch Daemon do not register. The README does not document what functionality depends on them beyond saying the helpers will not register, so if your workflow assumes background or daemon-side enforcement, verify that on your own build before relying on it. The README does state that `ShellSafetyService` is enforced daemon-side through AgentHelper and AgentUser as well as client-side, and that both XPC listeners require same-team code signing derived from the app's own signature. That is a defense-in-depth story that only fully applies when the helpers are present.

The third boundary is release cadence. The recent releases listed are v1.1.4.200 on 2026-08-30, v1.1.8.204 on 2026-09-01 and v1.1.9.205 on 2026-09-02. Whatever those version jumps represent, the spacing is days, not months. For a tool that can run shell commands as root, that is a reason to read the release notes before upgrading rather than to upgrade automatically.

AgentiLoop Agent! versus a terminal coding agent

The obvious comparison is a command-line coding agent. The difference is not the model, since AgentiLoop Agent! can point at Claude, GPT, Gemini, Grok, Mistral, DeepSeek, Qwen, Z.ai, BigModel, Hugging Face, OpenRouter, Ollama, vLLM, LM Studio, Codestral, Mistral Vibe and on-device Apple Intelligence, and a terminal agent can use several of the same providers. The difference is the surface area the agent can reach and how it reaches it.

A terminal agent lives in your shell and edits files. AgentiLoop Agent! is a SwiftUI application with XPC helpers, a Launch Agent and a Launch Daemon, and it drives other Mac applications through the Accessibility API. It also speaks AppleScript and JXA, which is why prompts like playing a playlist in Music or taking a photo with Photo Booth are in the README at all. If your work is entirely inside a repository and a shell, a terminal agent is a smaller thing to install and reason about. If your work spills into Xcode builds, GUI applications, iMessage and calendar, the harness is the point.

The local-model story is the other axis. The README states that LM Studio, Ollama and vLLM report their actual per-model context length, replacing a hardcoded 32K assumption. It also gives a concrete hardware note: only GLM-4.7-Turbo (32B) fits consumer hardware, described as 64 to 128GB Apple Silicon via Ollama. That is a specific claim about which local model is realistic, and it is more useful than a general "runs locally" line.

Licence, maintenance signals and upgrade cost

The repository is MIT licensed, which permits commercial and private use with the usual requirement to keep the copyright and permission notice. Nothing in the README adds terms on top of that, and the app itself is distributed through GitHub releases rather than a store. This is a description of the licence text, not legal advice; if you are embedding it in a product, read the LICENSE file in the repository.

The maintenance signal is straightforward. The repository is not archived, and the last push was on 2026-09-10. Releases landed on 2026-08-30, 2026-09-01 and 2026-09-02. The README also states there is a CI Build & Test workflow on every PR and 273 passing tests. Those are the maintainers' numbers, not an independent verification, and the README does not say what the tests cover.

The upgrade cost is where the design choices show. Context compaction, the read-before-edit gate and the tool-result spill-and-restore path are all described as rebuilt in the v1.1.x line. If you build from source, each upgrade means re-running the build, and the README's own troubleshooting suggests a clean when DerivedData goes stale. If you use the downloaded release, the app menu has a Check for Updates item that points at GitHub releases. There is no documented migration path for anything stored on disk between versions, and the README does not document rollback for the application itself, only task-level rollback through snapshots and `rewind_task`.

Editorial conclusion

Adopt AgentiLoop Agent! if you work on a Mac running macOS 26.4 or later, want an agent that can touch the Accessibility API, shell, AppleScript and Xcode rather than a browser tab, and are willing to build it from source with a paid Apple Developer team so the Launch Agent and Launch Daemon register. Do not adopt it if you need cross-platform agents, a Linux server component, or a stable release cadence: the README shows v1.1.4.200, v1.1.8.204 and v1.1.9.205 landing within four days of each other in late August and early September 2026, which is fast-moving for a tool that runs shell commands as root. Verify before you commit: that your Mac meets the macOS 26.4 target, that your chosen provider's API key works with the model you select, and whether you can live without the helpers, since the README states Option B builds are ad-hoc signed and the Launch Agent and Launch Daemon will not register without a Team ID.

Frequently asked questions

Official sources

1. AgentiLoop/Agent on GitHub
2. License: MIT
3. Project website
4. README
5. Releases