Install and first run

What you need before it is any use

AgentCron does not install or authenticate anything on your behalf, so this list is real rather than decorative.

A Mac with Apple Silicon. There is no Intel build. Windows would not compile — the channel between agents and the app is a Unix socket — and Linux is untested. No port is planned.

An agent CLI, installed and signed in. Claude Code, GitHub Copilot CLI or agy (Antigravity) — any one of the three is enough, and you can mix them, choosing per agent. A plain shell job works too if you want to schedule scripts rather than agents. AgentCron detects which ones are on your machine and tells you what it found. It cannot install one and it cannot log you in.

Node.js on your PATH. The small tool agents use to report progress, ask questions and request approval is a script that needs Node to run. Without it, agents still run but cannot talk back — which removes most of the point. It resolves node at the moment it runs, against the PATH your login shell exports, so nvm version switching is fine. What is not fine is Node not being on that PATH at all — the health check reports exactly that, and tells you which PATH it looked at.

Somewhere to point it. For code work, a git repo you are happy for an agent to branch from. Not your most important one, on day one.

What Gatekeeper will say

Until a build has been through Apple's checks, macOS refuses to open it and shows either *cannot be opened because the developer cannot be verified* or is damaged and can't be opened. Nothing is damaged — that second message is what macOS says about an app whose signature it cannot make sense of.

What you would be accepting:

• Apple has not scanned the build for malware.
• Nothing cryptographically ties the download to a named developer account, so if the file were swapped in transit or on the host, macOS could not tell you.
• You are relying on your own judgement instead of Apple's.

That is a real basis for a decision. It is a different one, and it is worth making deliberately rather than by clicking through a dialog.

If it is not a trade you want to make, wait for the signed release — that is a sensible call rather than a cautious one.

Which route actually works

The two messages above are two different failures, and the remedy for one does nothing for the other. It is worth knowing which one you have before you start clicking.

“cannot be opened because the developer cannot be verified” means the signature is valid but carries no Apple Developer ID. macOS will let you override that: Right-click → Open, or System Settings → Privacy & Security → Open Anyway. It asks once and leaves the check in place for the next thing you download, which is why it is the better of the two routes when it is available.

“is damaged and can’t be opened” means macOS could not validate the signature at all. There is no override for this one. Right-click → Open and Open Anyway both re-run the verification that is already failing, so they will not let you through no matter how many times you try — and it is easy to read that as a corrupt download when it is not. The only thing that opens a build in this state is removing the quarantine flag:

xattr -dr com.apple.quarantine /Applications/AgentCron.app

The -r is not optional. An app is a directory, and the quarantine flag is set on files inside it as well as on the bundle itself, so dropping it from the top level alone often changes nothing and looks like the command did not work.

That disables the check on that one file permanently, so it is a real decision rather than a formality — it is the same trade the warning is asking about, made explicitly and once. Check the message you actually got before running it; if you got the first message, use Right-click → Open instead and keep the check.

Both of these disappear when the build is properly signed, which is the actual fix and is on the pre-release list.

The first ten minutes

1. Let it look around. On first launch it checks which agent CLIs are on your machine and whether Node is where it expects. Fix anything it flags now — most later problems trace back to this screen.

2. Add a project. Point it at one repo.

3. Create one agent from a template. Read the prompt it filled in and change anything that does not match how your repo actually works. The prompt is the product; it is worth two minutes.

4. Press Run once. Watch this one. Read the command log while it works. This run is the honest test of whether the rest is worth setting up, and it costs you one run's tokens to find out.

5. Only then give it a schedule. Turn it on after you have watched it do the thing at least once. Nothing in a ready-made pack fires on its own.

When something is wrong

There is a health check built in that reports what it found — CLIs, Node, the agent channel, disk — and exports the whole thing to a file. Attaching that file to a bug report is the difference between a same-day answer and a week of back-and-forth, because otherwise every bug is happening on a machine nobody else can see.

Where to send that export is the gap: there is no issue tracker and no support address yet, because the repository is not public. Both arrive with the first release, and both will be in the open rather than in a private inbox — one person answering, and answers the next person can find.

Back up before an update or a large setup change

Open Settings → Updates and choose Back up now. The snapshot contains AgentCron's local state; it does not copy your repositories, worktrees, CLI credentials or Keychain passwords. Keep your repositories under their own normal backup policy.

Restore is deliberately refused while an agent is running. Park or finish the affected sessions, restore the chosen snapshot, then quit and reopen AgentCron before doing more work. The files that were replaced are moved aside rather than silently discarded, so a failed recovery still leaves something to inspect.

For day-to-day recovery:

• A blocked approval can be denied or allowed to expire; never work around it by running the gated action elsewhere.
• Resume a parked CLI conversation only when AgentCron has its exact conversation ID. If it does not, start a clean terminal and use the CLI's exact resume command; do not choose “latest” merely because two sessions share a folder.
• Use Settings → Storage to inspect disk use and preview cleanup. Cleanup never removes git worktrees automatically; removing a checkout remains an owner action.
• Export Diagnostics before changing a failing setup. The export removes known secret fields, but read it once before attaching it anywhere because project names, paths and tool output can still be private.

Two things that will happen

A schedule will be missed. The scheduler runs inside the app. If the Mac is asleep at 3am, the 3am run does not happen and there is no catch-up when it wakes.

Disk will disappear. Worktrees, screenshots, command output and run history add up faster than you expect. There is a storage view showing where it went and a cleanup that previews before deleting. Look at it in week one, not month two.