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.
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 MIT 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.