Troubleshooting

This one looks alarming and is completely harmless. macOS is just being protective: the very first time you double-click an app it hasn't seen before, it may warn you that Sparkle "can't be opened." Read that as a polite hello, not a problem. You're not in trouble, and nothing is broken.

Here's the trick. Find the Sparkle icon, right-click it (or hold Control and click), and choose Open from the menu. macOS asks one more time to confirm, click Open again, and you're in. You do this exactly once. After that, Sparkle launches like any other app on your Mac.

No Open option showing? Go to the Apple menu → System Settings → Privacy & Security, scroll down, and you'll spot a line about Sparkle with an Open Anyway button. Click it, confirm, done. That's it, you just got past your first gatekeeper. Welcome.

Gatekeeper, doing its thing. The double-click hands you a dead-end "can't be opened" dialog; the right-click does not. Right-click the app → Open → confirm, and macOS adds it to your allow list for good. One and done.

Already mashed the regular Open button five times and got nothing but the scary dialog? Head to System Settings → Privacy & Security, where an Open Anyway button is now sitting there waiting for you. One click and you're past it. Every launch after this is boring and normal, exactly like you want.

Gatekeeper quarantine on a first-run, unrecognized developer binary. Nothing exotic. Right-click → Open to register the exception, or hit Open Anyway under System Settings → Privacy & Security after the first blocked attempt. Allergic to clicking through GUIs? xattr -d com.apple.quarantine /Applications/Sparkle.app clears the quarantine bit directly and you never see the dialog. Either way, it's a one-time tax.

First rule: don't panic, and don't assume you broke something. You almost certainly didn't. The agent is the AI worker (running Claude Code under the hood) that actually builds your software, and it needs exactly two things to get going.

One: a brain to think with. Sparkle powers its building with your Claude Code Max subscription (Claude Pro, Max 5x, or Max 20x). Open Settings and confirm your subscription shows as connected and active. If it doesn't, reconnecting it is almost always the whole fix. No subscription yet? You can start one right here: https://claude.ai/referral/fD6TbYR9oA

Two: a clear job. Once the subscription is connected, check that the model you picked is available, then look hard at what you actually asked for. Vague requests make the agent hesitate. "Make it better" is a riddle; "change the heading to say Welcome and make it blue" is a job it can do in seconds. The more specific you are, the faster it flies. Specificity is a superpower, lean on it.

Before you start angrily re-prompting, check the boring thing first: is your Claude Code Max subscription (Pro / Max 5x / Max 20x) connected and active in Settings? A disconnected or lapsed subscription is a dead ringer for a "stuck" agent. Then confirm the selected model is actually available to your tier.

Billing checks out and it's still idle? It's the prompt. It's almost always the prompt. Knowing you, you fired off something ambitious and gloriously underspecified. Tighten it: name the file or feature, the exact change, and what "done" looks like. Specific in, fast out. That's the whole game.

Triage in order, cheapest check first:

1. Subscription. Sparkle bills through your Claude Code Max subscription (Pro / Max 5x / Max 20x), not an API key. Confirm it's connected and active in Settings; an expired or unlinked subscription presents as a dead agent every time.
2. Model availability. Verify the selected model is offered on your tier.
3. The prompt. Underspecified tasks stall. Give it constraints, acceptance criteria, and the target files. Garbage spec in, paralysis out.
4. The log. Read the agent's actual output before assuming it's hung. The error is usually right there, telling you exactly what it needs.

Good news, and it's the best news in this whole page: nothing the agent does is permanent until you say so. Every agent works on its own branch, which is just a private, parallel copy of your project. Your real project sits untouched the entire time. Nothing becomes official until you merge the work in, and that's the deliberate "yes, I want this" step that's always yours to make.

So if you don't love the result, you have two completely calm options:

• Ask for edits. Tell the agent what's off ("the button's too big," "this isn't what I meant") and let it revise.
• Throw it away. Discard the branch and it's like the attempt never happened.

Either way, you cannot hurt your main project by experimenting. So experiment boldly.

Nothing's real until you merge, so unclench. Two moves: keep iterating (tell the agent what's wrong and have it revise on the same branch), or cut your losses and torch the branch entirely. Because each agent is isolated on its own branch, blowing one away doesn't touch your main line or any other agent's work. This is the "recover cleanly" superpower you came for. Use it without guilt and without fear.

Work is branch/worktree-isolated, so you've got the usual two outs: request follow-up edits on the branch, or abandon it. Discarding a branch reverts that line of work to nothing and leaves main and every sibling worktree untouched. No sandbox state to clean up, no cross-contamination, no surprises. Exactly the isolation you'd build yourself if you had the time.

Breathe, you're not about to get hit with surprise fees. Your Claude Code Max subscription tier (Claude Pro, Max 5x, or Max 20x) sets how much included usage you get each month. Higher tiers include more usage and let more agents work at once.

The biggest lever in your hands is which models you use. More powerful models do more thinking, and more thinking spends your included usage faster. For everyday, routine tasks, a lighter model gets the job done beautifully while stretching your usage much, much further. Save the heavyweight models for the genuinely hard problems, that's where they earn their keep.

If you keep bumping into your limit, moving up a tier buys you real headroom. Compare and upgrade here: https://claude.ai/referral/fD6TbYR9oA

Your Claude Code Max tier (Pro / Max 5x / Max 20x) is your usage budget, and heavier models chew through it faster, especially with several agents running in parallel. Two knobs, both in your control: drop to a lighter model for the routine stuff (renames, copy tweaks, small fixes) and reserve the big guns for hard problems, or step up a tier for more included usage and more parallel agents. Compare tiers: https://claude.ai/referral/fD6TbYR9oA

Usage is metered against your Claude Code Max tier (Pro / Max 5x / Max 20x), not per-token billing on a key. The cost drivers are exactly what you'd expect: model weight and parallelism. Tune the model per task, run lighter models for routine work, and keep the top-tier models for tasks that actually justify them. If you're consistently saturating the tier, upgrading is the lever, not micro-optimizing every prompt: https://claude.ai/referral/fD6TbYR9oA

Debugging just means finding and fixing the spot where something went wrong, and it is a completely normal part of building. Nothing has gone off the rails if the first version is not perfect. Tell the agent what looks off in plain words ("this button does nothing when I click it"), and let it hunt down the cause. You do not have to know why it broke. You only have to notice that it did, and you are very good at noticing.

Debugging is where sloppy specs come back to bite you. The fastest fix lives upstream: keep tasks small and specific so there is less surface area to go wrong. When something does break anyway, hand the agent the symptom plus the file and let it bisect, instead of squinting at it yourself. You will spend far less time here than you would have hand-writing the thing in the first place.

Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?

The corollary for agent-built code writes itself: keep the spec tight and the changes small, and most of these "bumps" never get the chance to compound into something hard to unwind. Discipline up front is the cheapest debugging you'll ever do.