Everything Sparkle Does. Explained.
This is the complete feature reference. Every capability, every opinion, and why it exists.
The dance between thinking and doing.
Before you can build well, you need to think clearly. And in most coding tools, these two things are dangerously mixed together: a prompt you send becomes code immediately, whether you were ready or not.
Sparkle separates them deliberately. In Thinking mode, you have a private space to develop ideas, refine requirements, interview your own assumptions, and produce a real specification. Nothing you write in Thinking mode changes your codebase. Nothing is sent to an agent. It's yours to think in.
When your spec is ready, when you know what you want and why, you hand it to Build mode with one click. Your build agents read the spec, ask questions if something is ambiguous, and start building. If they hit something they don't understand, they flag it. You pull the question back into Thinking mode, work through it, and send the answer back. The loop is intentional. The best software is built this way.
Thinking
Redesign auth so sessions rotate tokens on every request.
Spec: rotate on refresh, 30-minute TTL, write each attempt to the audit log.
Build
sparkle/agent-3f2a · 4 files
Spec to PRD
Write a rough idea in Thinking mode. Sparkle helps you refine it into a real spec. Hand it to build agents as a PRD. Your agents reference it throughout the session.
Bidirectional Handoff
Thinking mode can send to Build. Build mode can flag questions back to Thinking. You're always in the right mode for the right task.
Separate Context
Everything in your Thinking sessions is stored separately from your build sessions. Your thinking history is yours. It informs your builds without polluting your codebase.
Context-Aware
Your Thinking mode knows what your agents are working on. Ask it questions about your build in progress. Get answers that are grounded in what actually exists in your project.
The terminal is still there. You just don't have to live in it.
The terminal hasn't changed since 1987. You still can't click to place your cursor. You can't highlight a word to delete it. There's no undo. There's no right-click. The AI that lives inside it is extraordinary. The interface you're forced to use to talk to it is a relic.
The Composer is what the terminal's input always should have been. It's a rich, modern editor that sits directly above the terminal. Click anywhere to place your cursor. Highlight and delete. Drag. Paste. Take your time. When it's exactly what you mean, send it, and the terminal receives a clean, complete instruction. You can also minimize the Composer entirely with ⌘J or by dragging the handle down, which gives Claude Code full-screen access to its TUI menus and your keyboard. ⌘J brings it back instantly.
$ claude code
● Waiting for your instruction…
Fix the padding on the login modal header
Screenshot Vision
Hit the camera icon, drag a crosshair over any part of your screen, and it drops in as a thumbnail. Claude Code sees exactly what you see: UI bugs, design mockups, error screens, anything. Your agents get vision without any configuration.
Ghost-Text Autocomplete
Every prompt you've sent is stored locally (up to 500). Start typing a familiar instruction and Sparkle completes it with a ghost suggestion in muted text. Press Tab or → to accept. Your history makes you faster.
Minimize to Bar
Press ⌘J or drag the handle to the floor to collapse the Composer to a 22px bar reading "▴ Message your agent." Full terminal access restored. ⌘J again restores the Composer.
Focus Routing
Typing in the terminal area automatically bounces focus to the Composer input. You can't accidentally fire raw keystrokes at Claude's TUI when you meant to write a prompt.
Building is faster when you talk.
A peer-reviewed study from Stanford, the University of Washington, and Andrew Ng measured speech at 153 words per minute versus 52 for keyboard, a 2.93x speedup with 20% fewer errors (Ruan et al., ACM PACM 2017, DOI: 10.1145/3161187). Even for fast typists who average 70–80 WPM, voice is roughly 2x faster.
Sparkle is built around this fact. Say "Hey Sparkle" at any time. The waveform bars in the sidebar animate from gray to blue→cyan, and Sparkle starts transcribing. Speak your instruction as naturally and as long as you need. The Composer fills with your words. Review them. Say "send it," and your agents have their instructions.
Nothing is ever auto-sent. You always review before commit. The pipeline is: wake → transcribe → fill composer → you review → send.
On-Device. Private. Free.
Powered by Parakeet-TDT, running locally on your Mac using sherpa-onnx. Your search index and voice never leaves your machine unless you want it to.
Wake Word Detection
"Hey Sparkle" triggers listening. The system uses a robust wake-word matcher that handles common mis-transcriptions (e.g. "hey sparkle" recognized even if transcribed as "hey sparql" or "hey sprinkle"). Smart, not brittle.
Stop Phrase
Say "send it" to submit your prompt. The Composer clears and your instruction is sent to the active agent. You never need to touch the keyboard for a full build instruction cycle.
Mute Toggle
Click the waveform in the sidebar to toggle between PASSIVE (gray bars, idle) and ACTIVE (animated blue→cyan bars, listening). The mic mute icon shows current state. Off by default only on request; on by default at launch.
LogoWaveform
The animated waveform bars live directly below the Sparkle logo in the sidebar. Gray when passive. Blue→cyan gradient when listening. This is your at-a-glance voice status indicator, always visible.
Don't build serially. Build in parallel.
Every other tool runs one agent at a time. You send a prompt, you wait, you get code, you send another prompt. Sparkle runs as many agents simultaneously as you want, each isolated in its own git worktree, each working on its own feature branch, each unable to interfere with the others.
Each agent is spawned from fresh origin/main. They can't branch off each other's work. They can't commit to the same branch. They can't race to merge into main. The orchestrator, your main Build agent, reads your spec, decomposes it into tasks, and spawns workers automatically. You watch the grid. You approve when needed. Workers merge when done.
2 orchestrators · 5 workers
Auto-Naming
The moment an agent receives its first prompt, it uses AI to generate a short, plain-English name for what it's working on (e.g. "User auth redesign", "API rate limiting", "Dark mode tokens"). The name updates automatically if the task changes significantly. Manual rename pins the name.
Attention-Aware Ordering
Agents that need a decision float to the top of the sidebar. Agents that are building happily sink to the bottom. You always know where to look.
Isolated Git Worktrees
Each agent lives in its own worktree directory outside the project tree, on its own feature branch, freshly checked out from origin/main. They cannot read or write each other's files. Collisions are architecturally impossible.
One Merge at a Time
When multiple agents finish simultaneously, merges to main are serialized. No race conditions. No dropped commits. One at a time, in order.
Staleness Detection
If an agent's branch falls behind origin/main (because another agent merged first), Sparkle shows an ahead/behind badge and nudges you to refresh before the agent reasons about the codebase.
Stack your Claude plans. Sparkle runs each agent on whichever has headroom.
A single Claude plan has a weekly cap. The moment you're running several agents in parallel, you'll hit it, and everything stops until the window resets. Sparkle lets you connect more than one Claude account (Pro, Max 5x, Max 20x) and automatically runs each agent under the one with the most headroom. You keep building instead of waiting.
It's private by design. Sparkle never sees or stores your Claude credentials. Each account is just a separate, isolated config directory that you log into with the normal Claude browser flow. Your own Claude binary authenticates itself, and Sparkle only manages the folders. Adding an account is one click, a fresh login in its own space.
How Sparkle picks an account per agent
- 1Honor a manual pin, if you set one for this agent.
- 2Exclude accounts that hit a real rate limit and haven't reset.
- 3Exclude accounts near a 5-hour or 7-day window cap.
- 4Among the rest, pick the lowest 7-day usage (tie-break: lowest 5-hour).
If every plan is tapped out at once, Sparkle falls back to your default account rather than blocking the agent.
Least-Used Plan Wins
Before each agent spawns, Sparkle picks the account with the lowest 7-day usage, tie-broken by the lowest 5-hour usage. Load spreads evenly across your plans automatically, so no single subscription burns down first.
Skip the Tapped-Out
Any account that's already near a 5-hour or 7-day window cap is excluded from selection. An agent never starts on a plan that's about to run dry mid-build.
Automatic Failover
If a running agent hits a real rate limit, Sparkle detects the limit message, benches that account until it resets, and routes the next job to one with headroom. No babysitting, no manual switching.
Pin When You Want Control
Auto-routing is the default, but you can pin any agent to a specific account and it will always run there. Useful when one plan has a model or entitlement the others don't.
Your agents don't need you at your desk.
Software gets built at night. On weekends. While you're on a plane. Sparkle's agents keep working when you walk away, and they know how to reach you when something comes up.
Push notifications hit your phone for anything that needs your call. The approval interface on mobile is designed for a 3-second decision: you see what the agent wants to do, you see Sparkle's risk assessment, you tap Approve or Reject. Your agent gets the answer. Building resumes.
| Tier | Trigger | Channels |
|---|---|---|
| Caution | Agent flagged a potentially risky action | Push + in-app |
| Dangerous | Agent wants to do something irreversible | Push + SMS + Email |
| Complete | Build session finished | Push + Email |
| Briefing | Overnight build summary | Email + Push at 7am |
Approval requested
Dangerous
Drop the staging database?
DB schema migration wants to run an irreversible command before rebuilding the schema.
Push · SMS · Email sent 2s ago
We'll notify you when the iOS app is ready. No spam.
Opinionated by default. Open if you want it.
| # | The Rule | What It Prevents | Modifiable in OSS? |
|---|---|---|---|
| 1 | No direct pushes to main: feature branch + PR required for all changes | Agents accidentally overwriting each other's work or shipping broken code directly to production | |
| 2 | Every worktree born from fresh origin/main: branching off a feature branch is blocked by default | Building on top of another agent's unfinished, unmerged work | |
| 3 | PRs are small and scoped: branches that grow past a size threshold get a "land or split" nudge | Massive, unreviewable PRs that no agent or human can reason about safely | |
| 4 | Worktrees are ephemeral: automatically deleted on merge, no lingering branches | Worktree graveyard: dozens of abandoned branches that become landmines for future agents | |
| 5 | One orchestrator owns main at a time: concurrent merges serialized | Two agents merging simultaneously, creating a conflict that corrupts the integration branch | |
| 6 | No force-push to main, ever: PR-merge only, enforced at hook level | Silently dropping commits that other agents already built on top of | |
| 7 | Agents refresh before they reason: decisions always cite current origin/main, not stale local view | Agents making architectural decisions based on code that's already been superseded | |
| 8 | Production deploys only through main: manual vercel --prod blocked by hook | Accidentally shipping an untested branch directly to your users | |
| 9 | Risk-tiered approvals: safe (auto), caution (in-app), dangerous (interrupt + push + SMS + email) | An agent deleting your database, pushing API keys to GitHub, or running irreversible commands without your knowledge | |
| 10 | Production Readiness Gate (0–100 score): ≥70 allowed; 50–69 explicit confirm; <50 blocked | Shipping something half-built because an agent said it was done | |
| 11 | Per-session cost cap ($5): exceeding it pauses the agent and fires a caution approval | Runaway agents spending your credits building something you didn't ask for | |
| 12 | Your credentials never pass through Sparkle: Claude Code authenticates itself with your own binary | Your API keys being captured in Sparkle's logs, telemetry, or classifier training data | - |
| 13 | Agents auto-name themselves after what they're building; manual rename pins the name permanently | The misery of six tabs all labeled "Agent" with no idea which one is doing what | |
| 14 | Commit small and often; Sparkle's roborev reviews every commit and flags issues in real time | Accumulating 200 lines of unreviewed changes that fail CI in a way nobody can bisect | |
| 15 | Public OSS repo is a one-way scripted export: private code, internal docs, and backend URLs are stripped before publishing; a hard leak-check gate fails the publish if any private content is detected | Accidentally open-sourcing your business logic, infrastructure URLs, or internal documents | - |
| 16 | Agent worktrees live outside the project tree: write-guard prevents agents from writing outside their designated directory | An agent that "helpfully" touches files it wasn't asked to, or a compromised prompt that tries to escape its working directory |
= Open source users can configure or remove this default. - = Architectural, not configurable.
If you look at this list and feel relief, that's exactly who Sparkle is built for. If you want to make different choices, the client is Apache-2.0 licensed. Pull requests that improve the compiled defaults are always welcome.
The terminal explained, action by action.
The terminal is visible in Sparkle. You see everything Claude Code does. Every command. Every file change. Every error. But you're not expected to decode any of it alone.
Highlight any text in the terminal with your cursor and a context menu appears. Ten actions, zero terminal knowledge required.
- Explain thisPlain-English explanation of the highlighted text
- CopyCopies to clipboard
- Search the webOpens a browser search for the highlighted text
- Run as commandSends the text directly to the terminal as a command
- Create taskCreates a new build task from the highlighted text
- Save as noteSaves to your project notes
- Fix itSends to the active agent with "fix this" context
- Brainstorm thisOpens Thinking mode with the highlighted text as context
- Open in editorOpens the relevant file in your default editor
- Add to promptAppends to the current Composer input
You always know exactly where your code is.
Every worker agent you run shows this pipeline in real time. Click any stage for details.
Everything stays private on your Mac. Until you decide otherwise.
Sparkle's base application is completely local. Your code, your prompts, your voice. Nothing leaves your computer. The client stores your prompt history in local storage. Voice transcription runs on-device with Parakeet-TDT, a best-in-class open-source model that never touches the internet. Even your credentials live in your macOS Keychain. Zero cloud calls. Just you, your terminal, and Claude Code running on your machine.
AI enhancements are a different layer entirely, optional cloud features you activate individually, powered by credits. Turn on just the ones you want. Turn them all on. Turn them off mid-session. When you buy Sparkle for $99, you get $200 in AI enhancement credits to start. When you run out, re-up anytime. Use less, pay less. Use more, get more.
Sparkle macOS app: $99 · 100% local · no credits required
You will receive $200 in AI Enhancement credits when you buy the Sparkle macOS app.
| Feature | 1980s terminal | Sparkle macOS clientPrivate · local | Sparkle + AI enhancementsPay-as-you-go with credits |
|---|---|---|---|
| Compose & prompt | |||
| Modern terminal editor | Not available. Stuck in the 1980s | Available. Click anywhere, select, delete, rewrite, undo/redo, every standard shortcut (⌘C/V/Z/A), and minimize to the terminal with ⌘J. | |
| A picture is worth 1,000 words tokens. Give Claude Code vision. | Not available. | Available. Local only. Camera → crosshair → thumbnail in the composer. Stored locally. | |
| Prompt history, autocomplete & Time Machine | Not available. | Available. Local only. Re-use past prompts, autocomplete as you speak or type, and jump back to any moment in your terminal (last 24h, local). | Needs AI credits. Up to a month locally, with optional cloud backup to keep it indefinitely. |
| Search your terminal history | Not available. | Available. Local only. Keyword search the last 24h of sessions. | Needs AI credits. Semantic (by meaning, not just text) + keyword, up to a month locally, with optional cloud backup. |
| Voice input | |||
| Voice-first dictation, always listening | Not available. | Available. Local only. On-device Parakeet-TDT. Always listening (one click to turn off); say “Hey Sparkle” to start, “send it” to finish. Fills the composer, never auto-sends. | Cloud voice for realtime streaming, higher accuracy, noise filtering, less word confusion (“write” vs. “right”), and auto re-wording when you correct yourself. |
| Orchestrate & build | |||
| Run many real agents in parallel | Not available. One at a time, unmanageable | Available. Local only. Multiple tabs, each a real PTY in its own isolated git worktree (fresh origin/main, no collisions). | Needs AI credits. An orchestrator reads your spec and spins workers up and down automatically. |
| Keep track of every agent at a glance | Not available. | Available. Local only. Color-coded status dots + attention-aware ordering (red / green / gray) so you see who needs you, plus staleness badges before agents reason on stale code. | Needs AI credits. Auto naming & re-naming of every agent tab so you remember what each one is doing. |
| Status pipeline: uncommitted → committed → PR → merged | Not available. | Available. Local only. Live, from local git status. | Needs AI credits. Adds a production stage, gated by the Readiness Gate. |
| Understand & navigate the terminal | |||
| See everything Claude Code does, in a modern UI | Available. That's all you have | Available. The same terminal, wrapped in a modern UI. | |
| Highlight any terminal text for instant actions | Not available. | Available. Local only. Copy, run as a command, search the web, send to your agent, or save a note/task to the built-in issue tracker, all local. | Needs AI credits. Plus AI actions: Explain this, Fix it, or Think it through. |
| Stay in control (approvals & safety) | |||
| See, and approve, what your agents do | Not available. You watch the cursor | Available. Local only. A local classifier risk-tiers every action (safe / caution / dangerous); agents that need you float to the top with a red dot; approve or reject in-app. | Needs AI credits. Also pushed to your phone. Approve from the iOS app; dangerous actions interrupt + push + SMS + email (coming soon). |
| Production Readiness Gate before any deploy | Not available. | Not available. | Needs AI credits. A 0–100 score across security, quality, and completeness. Below 50 blocks the deploy (configurable). |
| Safe by default | Not available. Easy to do the wrong thing | Available. Local only. No direct pushes to main: PRs enforced (configurable); your credentials stay in the macOS Keychain, never logged or sent. | Available. Local only. Sparkle never sees your API key in plaintext. |
| Think & plan | |||
| Thinking mode: brainstorm, then build | Not available. | Not available. | Needs AI credits. A safe space that never touches your code. Refine an idea into a spec, then hand it to a Build agent in one click. |
| An AI that understands your whole project | Not available. | Not available. | Needs AI credits. Build agents sync their progress to the Thinking context and flag ambiguity back to you, a bidirectional Think → Build → Think loop. |
| Privacy & data | |||
| Your code and prompts stay on your Mac | Available. | Available. Local only. Source code is never uploaded; prompts live in local storage and are never transmitted. | Available. Local only. Cloud features never access your source code; search sends only embeddings. |
| Voice never leaves your machine | Not available. N/A | Available. Local only. Parakeet runs on-device. | Optional cloud voice; base stays local when off. |
| Credentials in Keychain | Not available. N/A | Available. Local only. API key in your macOS Keychain (never logged or sent). | |
| Open source. Audit every line | Not available. N/A | Available. All client code is public (Apache-2.0). | |