Files

T

abkslmandnucleic 9cc1f07daa nvrsion: Add Canary release channel, fix truncation text wrapping, add function to use the on-device model to cross-check file permissions against commands for legitimacy, refactor chat logic to explore file permissions with on-device model validation, and adjust website/index.html to include “Iterate at the speed of thought” as a primary selling point.

Nucleic-Promote: 1
Co-authored-by: Nucleic <[email protected]>

2026-07-01 19:41:33 -07:00

28 KiB

Raw Blame History

Nucleic — Product Concept

Brief for the website agent. This document is the single source of truth for building Nucleic's marketing + download site. It explains what Nucleic is, who it's for, what makes it unique, and how to talk about it. The closing sections (§14–17) give concrete site structure, copy hooks, and honesty guardrails. Everything here is grounded in the actual product as it exists in the codebase today — don't invent features beyond what's listed, and respect the "status" notes in §13 so the site never over-promises.

Maintainer's note. This brief was rewritten against the shipping code (June 2026). The live website at website/index.html predates the Grok backend, Orchestra, and nvrsion, and still describes only "Claude Code + Codex" — treat this document, not the current site, as the source of truth, and reconcile the site from here.

1. One-liner

Nucleic is mission control for a fleet of AI coding agents. It runs many Claude Code, Codex, and Grok sessions in parallel — each sealed in its own git worktree and branch — and gives you one native Mac cockpit to start them, watch them, approve what they do, and merge their work back. A companion iPhone app lets you approve and unblock agents from anywhere on your network.

Alternate one-liners (pick by context):

"Run ten coding agents at once — without them stepping on each other."
"The cockpit for parallel AI coding."
"Your agents work in parallel. You stay in control."
"Orchestrate Claude Code, Codex, and Grok side by side, from your Mac and your phone."

2. The problem

AI coding agents are good enough now that the bottleneck isn't the agent — it's you. A single agent in a single terminal means you babysit one task at a time: watch it work, answer its permission prompts, review the diff, merge, repeat. Try to run several at once and they collide — same files, same branch, same working directory — and you lose track of which one needs you.

The hard parts of running agents in parallel are isolation, attention, and trust:

Isolation — each agent needs its own sandbox so concurrent edits don't corrupt each other.
Attention — with N agents running, you need to know which one needs you right now.
Trust — agents ask to run commands and edit files; you need a real, fast approval gate, not a wall of yes/no you rubber-stamp or a terminal you have to babysit.

Nucleic is built around exactly these three problems.

3. What Nucleic is

A native macOS app (Swift 6.2 + SwiftUI, strict concurrency) that wraps the claude, codex, and grok command-line agents as managed subprocesses and orchestrates many of them at once. The Mac is the host — it does all the real work: spawning the agents, owning the repos, running git, holding the authoritative state. The iPhone app (NucleicRemote) is a thin, secure remote control: monitor sessions and answer approvals on the go.

The mental model is small and consistent:

Project — a git repo you've registered (with optional per-project setup script, default backend, and approval defaults).
Session — one agent run. It belongs to a project, owns a worktree, has a backend (Claude, Codex, or Grok), a live status, and a transcript. (In the app's UI these are labeled "chats"; this brief calls them "sessions" for clarity — they're the same thing.)
Worktree — the isolated git worktree + branch a session works in. This is the magic: every session gets its own real checkout, so ten agents can edit the same repo simultaneously without ever touching each other's files.

Under the hood, one actor — the SessionController — is the single writer of each session's state. The UI, the iPhone sync server, and the on-disk database are all subscribers to one normalized event stream with a canonical, monotonic sequence number. Everything you see — on the Mac and the phone — is a live projection of that one authoritative state on the host. Two renderers, one source of truth.

4. How it works (the 60-second version)

Start a session. Pick a project, a base branch, a backend (Claude, Codex, or Grok), a model, and type a prompt. Nucleic spins up a fresh git worktree (git worktree add … -b nucleic/<name>), runs your optional setup script (e.g. npm install) in it, and launches the agent.
Watch it work. A live transcript streams the agent's prose, thinking, and tool calls; a diff view tracks exactly what it's changing — including uncommitted work — as it goes.
Approve what matters. When the agent wants to run a command or touch something risky, Nucleic surfaces a real permission prompt — on the Mac and pushed to any paired phone. You allow, deny, modify-and-allow, or "always allow this in this session." First responder wins.
Run many at once. Repeat. Sessions are grouped by who needs you — needs-approval and waiting-for-input float to the top — so the answer to "what needs me?" is one glance away.
Ship it. When a session's done, review its diff and merge / rebase / squash it back, open a PR via gh, or discard. Or, on a Nucleic Control project, flip on Autoship and let finished agents merge themselves.

5. Features — the unique ones (lead with these)

These are the differentiators. They're what makes Nucleic Nucleic and not "another agent UI."

⭐ Parallel git-worktree isolation (the defining feature)

Every session runs in its own real git worktree and branch — a separate working directory on disk (<repo>/.nucleic/worktrees/<slug> on branch nucleic/<slug>). That means you can run ten agents against the same repository at the same time and they physically cannot corrupt each other's edits. No stashing, no branch-juggling, no "wait for the other one to finish." This is the core insight the whole product is built on, and it's what no single-terminal workflow can give you.

⭐ Three agents, one cockpit (Claude Code, Codex, and Grok)

Nucleic wraps three genuinely different CLI agents behind one normalized backend protocol:

Claude Code — via stream-json, with interactive approvals through an in-process MCP permission server.
Codex — two backends against the same contract: codex app-server (the default; interactive approvals over JSON-RPC) and codex exec (an unattended, fail-closed fallback).
Grok — xAI's agent over ACP (the Agent Client Protocol; standard JSON-RPC over grok agent stdio), with native interactive approvals.

They have genuinely different approval models, output formats, and session semantics — Nucleic normalizes all of it into a single event stream and a single approval flow. Pick the backend per task right from the model picker (the SKU routes it: a claude-* model runs Claude; a gpt-*, o3*, o4*, or *codex* model runs Codex; a grok-* model runs Grok). Run them side by side and review them the same way.

⭐ Real interactive approvals (not TTY scraping)

Most "agent UIs" either run agents fully autonomous (scary) or screen-scrape a terminal (fragile). Nucleic registers an in-process permission server and gets first-class, per-session approval prompts straight from the agent — every gated command and file edit pauses the agent and waits for your decision. Risk-aware: each request is classified (read-only, write, execute, network, destructive, host-exec) and the loud ones demand extra deliberation. You can allow, deny, modify-and-allow (edit the tool input first, where the backend supports it), or "always allow this tool in this session" to cut the noise without losing control. Whoever answers first — Mac UI or a paired phone — wins; the decision is stamped with who made it, and late responders are told it's already resolved.

Orchestra is Nucleic's orchestration mode, picked from the effort menu like any other level. It runs the agent at maximum thoroughness (xhigh effort) and rides a standing-consent instruction in on every turn that grants the agent blanket permission to spin up its own parallel subagents (its Task/Agent tools), with those spawn tools pre-allowed so the fan-out isn't a wall of approvals. It's a one-way latch within a session and is marked with a gold sparkle. Orchestra's full power — pre-allowed multi-agent fan-out — is reserved for Nucleic Control projects (the hardened path described below) and is most developed for Claude Code today. (Nucleic doesn't spawn the subagents itself; it grants the consent and the agent decides how to use it.)

⭐ Approve from your phone (the iPhone remote)

The companion iOS app (NucleicRemote) turns "an agent is blocked waiting on me" into something you can answer away from the desk. It pairs to your Mac with a QR scan, discovers it over the local network (Bonjour), and speaks an end-to-end-encrypted protocol. At the default "approve" scope you can watch sessions, answer approvals, and send follow-up input; at "control" scope you can also start sessions, interrupt, integrate (merge/rebase/squash/discard), and change a session's model/effort/autoship mid-stream. Whoever answers first — Mac or phone — wins; the prompt collapses everywhere else. (Today this works over your local network; see §13 for the cloud-relay roadmap.)

⭐ End-to-end encrypted remote

The Mac↔iPhone link is end-to-end encrypted with the Noise protocol (XXpsk0 for QR pairing, IK for reconnect; Curve25519 / ChaChaPoly / SHA-256 via CryptoKit). Device identity keys live in the iOS Keychain (this-device-only, after-first-unlock). When the cloud relay ships, it's designed to broker ciphertext only — it can never read your code, diffs, or transcripts. For a tool that touches proprietary source, that privacy posture is a feature, not fine print.

⭐ Autoship — agents that merge themselves

Flip the Ship toggle and a session merges its own branch into the target branch the moment its work is genuinely done — model-gated (it only fires when the turn is classified .completed, never mid-task or while the agent is asking a question). A merge queue serializes merges one-at-a-time per (project, target) and always squash-merges against the live tip, so parallel agents never clobber each other; a conflict cleanly aborts with the branch left intact, flags a sticky conflict marker, and asks for a human — but keeps Ship armed so the work re-ships on the next clean merge rather than blindly retrying (only a hard merge error disarms Ship outright). Hands-off when you want it, safe by construction. Autoship requires Nucleic Control on the project (see below) — the hardened, observed-git path — so unattended merges only run where Nucleic manages the repo and detects git operations directly.

⭐ Nucleic Control — repos Nucleic manages end to end

A Nucleic Control project is one Nucleic clones and owns under ~/.nucleic/control/ — out of iCloud and away from manual edits. Control projects get the hardened treatment:

Sandboxed. Their sessions run inside a managed Linux container built on Apple's in-process containerization framework (daemonless VMs bounded by the app process), so agents run contained, not loose on your machine. By default all Control sessions share one primary container; an optional per-backend split (separate Claude/Codex/Grok containers) avoids agents killing each other's processes. The whole container service is opt-in via an app-wide switch.
Git observed with certainty. Inside the container a git interceptor shim (plus gh and an opt-in command tracer) sits ahead of the real tools on PATH: it runs them transparently and reports each mutating operation back to Nucleic, so merges and conflicts are detected as events, not guessed from command text.
A private control plane. The in-container approval server and interceptor shims talk to the host over a vsock-relayed Unix socket (default on) instead of a TCP port on the VM gateway — no macOS firewall prompts, no exposed ports. (Legacy TCP-over-gateway remains as a fallback.)
Autoship- and Orchestra-eligible. Only Control projects can turn on Autoship, and Orchestra's pre-allowed fan-out is gated to them.

⭐ Real per-file locking & conflict awareness

For agents working in the same lock domain (e.g. a parent session and its children), an explicit LockManager grants per-file locks all-or-nothing, queues waiters FIFO with demotion, detects deadlock (wait-for cycles), and re-grounds a session on the latest content when it acquires a lock. A ConflictCoordinator turns overlapping edits and failed integrations into clear, human-resolvable stops rather than silent corruption. This is the machinery that makes Autoship and nested sessions safe.

⭐ Idea inbox (capture now, dispatch later)

Hit ⌘T to jot down an idea while your other agents are busy. Nucleic keeps an inbox of ideas you can later "dispatch" as a full agent run with one click. It's the natural front door to a parallel workflow: capture the thought, let the fleet pick it up when you're ready.

6. nvrsion — shared-trunk versioning for agents (Beta)

nvrsion is an opt-in, Beta versioning mode for Nucleic Control projects that swaps per-session worktree isolation for a different model: every session edits one shared trunk checkout, and each individual edit lands instantly as a path-scoped commit (briefly held to protect against an idle race), then accumulated trunk work is promoted to the base branch as one squashed commit — either when you say so or via a short auto-integrate timer. Paired with the LockManager, it lets many agents collaborate on the same tree in real time, per file and per edit, without branch juggling.

It's real and fully landed in the codebase, but it's a deep concept and a different mental model from the headline worktree-isolation story. Treat classic worktree isolation as the default and the headline; present nvrsion as a clearly-labeled Beta option for Control projects — don't lead with it.

7. Features — the rest (table-stakes, done well)

Live transcript — streaming markdown, collapsible thinking, compact expandable tool-call rows color-coded by risk, with file edits linking to the change.
Diff & workspace — each session tracks its diff against a stable base commit (committed and uncommitted work), surfaced as changed-file counts and a per-session diff view. Alongside it, a dockable multi-panel workspace gives you Files (tree), Editor, and Terminal panels you can save as named layouts. (A fully-realized split/unified, per-hunk diff reviewer is still maturing — see §13.)
Status at a glance — one consistent set of status states everywhere (provisioning, running, awaiting-approval, awaiting-input, finished, interrupted, error), with "needs you" surfaced first.
Native resume — uses each CLI's native resume, but keeps the local JSONL transcript as the UI's source of truth, so reopening a session replays instantly without re-running the agent.
Per-project setup scripts — provision each new worktree (install deps, etc.) before the agent starts; a block-or-warn policy decides what happens if setup fails.
Flexible integration — merge (--no-ff), rebase, squash, open a PR via gh, or discard, with clean conflict surfacing (including handing the conflict back to an agent to resolve).
Build & Run panel — detects build/run commands from a project's manifests and streams their output into an in-app console.
Usage & quota — for Claude (OAuth) sessions, gauges for the context window plus 5-hour and weekly usage sit over the composer and on Home.
On-device assists — an Apple Foundation Model queue runs locally for turn classification, tool-call summaries, and nvrsion summaries; surfaced in the sidebar's "AI" tab.
Activity & streaks — a GitHub-style activity grid and a consecutive-days streak badge on Home.
Accessibility — four color-vision modes (standard / deuteranopia / protanopia / tritanopia) and five text-size levels, applied app-wide.
Local-first — your repos, transcripts, and metadata live on your machine. Transcripts are append-only JSONL on disk; metadata is local SQLite (GRDB, WAL). Private keys live in the Keychain. Nothing is uploaded to run.

8. Mac + phone — two renderers, one source of truth

The Mac is the cockpit and the host of record; the phone is a pure projection of host state. Neither holds canonical state — both observe the SessionController and send intents, so a decision made on one collapses on the other. Today the phone pairs and works over your local network; the cloud relay that would extend it beyond the LAN (and add push notifications) is designed and partly built but not yet deployed (§13).

9. Trust & privacy

Local-first by design. Code, transcripts (JSONL), and metadata (SQLite) stay on your Mac.
End-to-end encrypted remote. The phone link is Noise-encrypted; a future relay brokers ciphertext only.
Real approval gating. Every gated command and edit pauses for a human decision, risk-classified, first-responder-wins, with an audit of who decided.
Sandboxed agents. Nucleic Control runs agents inside managed Linux containers with observed git, a private vsock control plane, and no exposed network ports.

10. Who it's for

Individual developers who've outgrown one-agent-at-a-time and want to parallelize: kick off a refactor, a test-fixing pass, a docs sweep, and a spike — all at once, all reviewable.
Power users of Claude Code / Codex / Grok who want orchestration, isolation, and a real review surface instead of juggling terminals and branches by hand.
People who don't want to be chained to the desk — start work in the morning, approve from your phone over coffee, merge from the cockpit.

Primary persona: a productive engineer who already trusts AI agents for real work and wants to run more of them, safely, in parallel.

11. Why Nucleic over the alternatives

Doing it by hand	With Nucleic
One agent per terminal; you babysit each	Many agents in one cockpit; triage by who needs you
Agents collide on the same working dir	Each agent isolated in its own worktree + branch
Stash/branch-juggle to run two things	Spin up parallel sessions; merge each back independently
Locked to one agent vendor	Claude Code, Codex, and Grok behind one protocol
Approvals = a terminal you can't leave	Real approval prompts, on Mac and phone, first-responder-wins
Tied to your desk	Approve and unblock from your iPhone, end-to-end encrypted
Merge each branch yourself	Optional Autoship merges finished work for you, safely queued
Agents loose on your machine	Nucleic Control sandboxes them with observed git

12. Platform & requirements

Host: macOS 26 (Tahoe) on Apple Silicon (required by the in-process containerization framework). Native Swift 6.2 / SwiftUI app; updates via Sparkle.
Remote: iPhone app (NucleicRemote), iOS 17+, pairs to the Mac over the local network today; an encrypted cloud relay is planned so it works from anywhere.
Agents: bring your own CLIs and accounts — claude (Claude Code), codex, and grok. Auth is the agent's own: Claude via ANTHROPIC_API_KEY/OAuth, Grok via XAI_API_KEY or a grok CLI login. Grok is the newest backend and runs on the host by default; running it inside Nucleic Control's sandbox container is still being finished.
Optional: the gh CLI for PR creation; Nucleic Control's sandbox pulls its Linux sandbox and kernel images on first use.

13. Status & honesty notes (read before writing any copy)

Nucleic is early and pre-1.0 — it ships as a private Beta. The site can be confident and aspirational about the vision, but must not misrepresent availability. Current reality:

Working today (confirmed in the codebase):

Parallel, worktree-isolated sessions on macOS.
Three backends — Claude Code, Codex (interactive app-server + unattended exec), and Grok (the newest; runs on the host by default).
Live transcript, diff tracking, interactive risk-aware approvals (Mac + iPhone over LAN), always-allow rules, modify-and-allow.
Autoship + merge queue, and Orchestra (both gated to Nucleic Control projects).
Explicit per-file locking + conflict coordination.
Nucleic Control: managed clones, shared sandbox container (Apple containerization framework), vsock control plane, git/gh interceptors.
nvrsion (Beta, Control-only, opt-in).
The idea inbox (⌘T capture + dispatch), multi-panel workspace, Build & Run panel, quota gauges, on-device summaries, activity/streaks, accessibility modes.
The iPhone remote over LAN (monitor, approve, send input; control scope adds start/integrate/ interrupt/model-effort changes), end-to-end encrypted.
Local-first storage (JSONL transcripts + SQLite metadata).

Partial / still maturing (don't present as finished):

A true cross-project, density-first dashboard grid sectioned by urgency. Today Home is a greeting
- stat cards + activity grid + idea inbox, and per-project "needs attention" lives on the project view.
A fully-realized split/unified, per-hunk, syntax-highlighted diff reviewer (diff is tracked and viewable; the rich reviewer is not all there yet).
Per-session sandbox containers for non-Control projects (the toggle exists but isn't user-settable yet; Control sessions share the primary container).
The idea inbox's AI impact-ranking/triage.
Codex/Grok parity inside the Control container (sandbox/auth/interceptor end-to-end is pending on-hardware verification; Claude is the proven path there).

Planned / not yet implemented (frame as roadmap):

Menu-bar item and native push notifications on the Mac — not implemented yet. Don't claim a menu-bar agent or OS notifications.
Cloud relay + remote push — the Cloudflare Worker/Durable-Object edge (nucleic-edge: ciphertext relay, relay-token lifecycle, APNs push) is built and unit-tested but not deployed, and the host-side relay transport isn't wired. So the phone is LAN-only end to end today; present "approve from anywhere" / push as roadmap, not shipped.

Distribution is not yet public. There is no public download, App Store, or TestFlight release. The release pipeline is fully wired and exercised on Beta — five channels (dev/canary/beta/rc/stable) with distinct bundle IDs that coexist, Developer ID signing + notarization + DMG + Sparkle appcasts on Cloudflare R2, and an iOS App Store Connect path — but nothing has shipped to the public. Do not present a live "Download" button. The primary CTA must be a waitlist / "Request early access" capture. Mark the product Beta · pre-1.0 throughout, and don't quote an exact version number (the VERSION file lags the actual Beta builds).

Treat §13 as the guardrail: market the capabilities that exist, frame the rest as roadmap, and keep the primary CTA honest (waitlist over fake download) until distribution lands.

14. Suggested site structure (for the website agent)

A single-page marketing site + a download/early-access section works well. Suggested sections:

Hero — the one-liner, a sharp subhead, primary CTA (request early access), and a visual of the cockpit (several sessions, a couple "needs you" badges).
The problem — the "you're the bottleneck / agents collide" framing from §2, kept tight.
The core idea — parallel worktree isolation, explained with a simple diagram: one repo → many isolated worktrees → many agents at once.
Feature showcase — lead with the ⭐ unique features (§5), each with a short headline + one-sentence payoff + a visual. The table-stakes features (§7) can be a denser grid below.
Mac + phone — the two-renderers story: cockpit on the Mac, approve-from-the-network on the phone, end-to-end encrypted.
Trust & privacy — local-first, E2E encryption, real approval gating, sandboxed agents. A genuine differentiator; give it room.
How it works — the 5-step flow from §4.
Who it's for — §10.
FAQ — pull from the facts here (which agents, which platforms, is my code uploaded, how isolation works, what's the phone for, when can I get it).
CTA / footer — early-access capture, repeated.

When you update the live site, fold in what it's currently missing: the Grok backend (three agents, not two), Orchestra, and the nvrsion (Beta) option.

15. Voice, tone, and naming

Name: Nucleic. The iPhone app is NucleicRemote (one word). The product was codenamed "Conductor" internally in early docs — do not use that name on the site.
Orchestra is a real product feature name — keep it capitalized and distinct from the generic "orchestration" metaphor.
Tone: confident, technical, precise — talking to engineers who know what a worktree and an approval prompt are. Not hypey, not enterprise-buzzwordy. Respect the reader's intelligence.
Metaphor family: cockpit / mission control / fleet / orchestration. "Nucleic" + "nucleus" + parallel "cells" of work is a fair visual/thematic well (sessions as isolated cells orbiting one nucleus of control — the brand atom). Keep it subtle.
Avoid: "magic," "10x," "revolutionary," "AGI," and any claim of full unattended autonomy — the whole point is control. Don't promise the agent does it all unattended; promise you can run many and stay in command.
Backends: say "Claude Code, Codex, and Grok" (three). If you go deeper, note Codex has both an interactive and an unattended mode and that Grok is host-only today; don't claim cross-agent parity for Orchestra (it's most developed for Claude Code).
Recurring proof-points to weave in: isolation (worktrees), parallelism (the fleet), control (real approvals), reach (phone), trust (E2EE, local-first, sandboxed Control).

16. Ready-to-use copy snippets

Use, adapt, or rewrite — these capture the positioning.

Hero headline: "Run a fleet of coding agents. Stay in command."
Hero subhead: "Nucleic runs Claude Code, Codex, and Grok in parallel — each agent sealed in its own git worktree — with one Mac cockpit to watch, approve, and merge their work. Approve from your phone, too."
Worktree section: "Ten agents. One repo. Zero collisions. Every session works in its own git worktree and branch, so concurrent agents never touch each other's files."
Backends section: "Three agents, one cockpit. Claude Code, Codex, and Grok behind one approval flow — pick the right one per task and review them the same way."
Approvals section: "Agents ask. You decide. Real per-action approval prompts — on your Mac and pushed to your phone — gate every command and edit. First to answer wins."
Phone section: "An agent's blocked. You stepped away. Approve it from your phone, end-to-end encrypted, and keep the fleet moving."
Autoship section: "Finished work, merged for you. On a Nucleic Control project, flip on Autoship and completed agents merge their own branch — safely queued, conflict-aware, never mid-task."
Control section: "The hardened path. Nucleic Control clones and sandboxes your repo, watches git directly, and keeps agents contained — so unattended work runs where Nucleic is in command."
Privacy line: "Local-first by design. Your code and transcripts stay on your machine; the remote link is end-to-end encrypted."
CTA (pre-release): "Be first in the cockpit — request early access."

Source of truth for this brief: Nucleic's shipping codebase and internal design docs (PLAN.md, RUNTIME_ARCHITECTURE, BACKEND_PROTOCOL, ADAPTERS, WORKTREE_MANAGER, LOCKING, SYNC_PROTOCOL, CLOUD_INFRA, VSOCK_CONTROL_PLANE, NVRSION, UX_MACOS, UX_IOS, BUILD.md), as of June 2026. When in doubt about a claim, prefer the capability that demonstrably exists in code over the roadmap item, and honor the status notes in §13.

28 KiB Raw Blame History Unescape Escape