nucleic/NUCLEIC_CONCEPT.md

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. A section at the end (§11–13) gives concrete site structure, copy hooks, and honesty guardrails. Everything here is grounded in the actual product — don't invent features beyond what's listed, and respect the "status" notes so the site doesn't over-promise.

---

1. One-liner

Nucleic is mission control for a fleet of AI coding agents. It runs many Claude Code and Codex 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.

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 and Codex 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 + SwiftUI) that wraps the claude and codex 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. 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 and defaults).
• Session — one agent run. It belongs to a project, owns a worktree, has a backend (Claude or Codex), a live status, and a transcript.
• 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.

Everything you see — on the Mac and the phone — is a live projection of one authoritative state on the host. Two renderers, one source of truth.

---

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

1. Start a session. Pick a project, a base branch, a backend (Claude or Codex), 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.
2. Watch it work. A live transcript streams the agent's prose, thinking, and tool calls; a live diff view shows exactly what it's changing — including uncommitted work — as it goes.
3. 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 your phone. You allow, deny, or "always allow this in this session." First responder wins.
4. Run many at once. Repeat. The Dashboard shows every session across every project, sorted by who needs you — needs-approval and waiting-for-input float to the top.
5. Ship it. When a session's done, review its diff and merge / rebase / squash it back, open a PR, or discard. Or 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. 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.

⭐ Two agents, one cockpit (Claude Code and Codex)

Nucleic wraps both Claude Code and OpenAI's Codex behind one normalized backend protocol. 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. Run Claude on one task and Codex on another, side by side, and review them the same way. Pick the right agent per task without changing tools.

⭐ 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: destructive or network actions are visually loud and require extra deliberation. "Always allow this tool in this session" cuts the noise without losing control.

⭐ Approve from your phone (notification-first iPhone remote)

The companion iOS app turns "an agent is blocked waiting on me" into a push notification you can answer from anywhere. Low-risk approvals resolve right from the notification; high-risk ones open the app behind Face ID. Live Activity / Dynamic Island shows running sessions and pending approvals at a glance. Whoever answers first — Mac or phone — wins; the prompt collapses everywhere else. Your fleet keeps moving even when you're away from the desk.

⭐ End-to-end encrypted remote

The Mac↔iPhone link is end-to-end encrypted (Noise protocol; keys in the Secure Enclave). Pairing is a QR scan. When the cloud relay ships, it brokers 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 your default branch the moment its work is genuinely done — model-gated (it only fires when the agent says it's finished, never mid-task). A merge queue serializes merges per branch and always merges against the live tip, so parallel agents never clobber each other; a conflict cleanly stops and asks for a human instead of blindly retrying. Hands-off when you want it, safe by construction. Autoship requires Nucleic Control on the project (see below) — the hardened, sandboxed path — so unattended merges only run where Nucleic manages the repo and observes git 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 by default:

• Sandboxed project-wide. Their sessions run in Nucleic's single primary managed container (one shared container across control projects), so agents run contained, not loose on your machine. (A future per-session-container mode is reserved; control projects share the primary one for now.) Sandboxing still respects the app-wide container service switch — with it off, sessions run on the host.
• Git observed with certainty. Inside a control container a git interceptor shim sits ahead of real git on PATH: it runs git transparently and reports each mutating op back to Nucleic, so merges and other git operations are detected as events, not guessed from command text.
• Autoship-eligible. Only control projects can turn on Autoship.

⭐ Per-session sandbox containers

Outside Nucleic Control, any project can opt a session into its own isolated sandbox container (built on Apple's native container runtime), with its own filesystem view and controlled network. Per-session containers spin up per session, idle out when nothing's running, and get cleaned up on session end. (Control projects instead share Nucleic's primary container — see above.)

⭐ Idea inbox (capture now, dispatch later)

Hit Cmd-T to jot down an idea while your other agents are busy. Nucleic keeps a triaged inbox of ideas — AI-ranked by impact — that 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. Features — the rest (the table-stakes done well)

• The Dashboard — every session across every project in one density-first grid, sectioned by urgency ("Needs attention" / "Running" / "Done, ready to integrate"). The answer to "what needs me?" is always one glance away. Inline-approve low-risk prompts without even opening a session.
• Live diff view — per-session diff against the base commit, showing committed and uncommitted work, split/unified, syntax-highlighted, per-hunk navigation. This is where you review before merging.
• Live transcript — streaming markdown, collapsible thinking, compact expandable tool-call rows color-coded by risk, with file edits linking straight to the diff.
• Status at a glance — one consistent set of status glyphs everywhere (needs-approval, waiting-for-input, running, done, idle, error), with badge counts and "needs you" sorting.
• Native resume — uses each CLI's native resume, but keeps a local 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.
• Flexible integration — merge, rebase, squash, open a PR via gh, or discard — with clean conflict handling, including "ask the agent to resolve."
• Menu-bar + notifications — a menu-bar item counts sessions needing you; native, actionable notifications fire when an agent needs approval or finishes.
• Local-first — your repos, transcripts, and metadata live on your machine. Transcripts are plain JSONL on disk; metadata in local SQLite. Nothing is uploaded to run.

---

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

---

8. 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 and Codex 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, E2E encrypted
Merge each branch yourself	Optional Autoship merges finished work for you, safely

---

9. Platform & requirements

• Host: macOS (Apple Silicon). Native SwiftUI app.
• Remote: iPhone app (NucleicRemote), pairs to the Mac over LAN today; encrypted cloud relay planned so it works from anywhere.
• Agents: the claude (Claude Code) CLI today; codex support is built against the same protocol. Users bring their own agent CLIs / accounts.
• Optional: Apple's container runtime for per-session sandboxing; gh for PR creation.

---

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

Nucleic is early and pre-1.0. The site can be confident and aspirational about the vision, but must not misrepresent availability. Current reality:

• Working today: parallel sessions on macOS, worktree isolation, live transcript + diff, interactive approvals, the dashboard, Autoship + merge queue, per-session containers, the idea inbox, and the iPhone remote over LAN (monitor + approve + send follow-up input).
• In progress / planned: the Cloudflare cloud relay + push notifications (so the phone works beyond the local network), and broader polish (usage/cost display, policy approvals).
• Distribution is not yet wired. There is no notarized public download or App Store build yet — builds are currently local/ad-hoc-signed. Do not present a live "Download" button that implies a notarized public release exists. Instead, the download/CTA should be a waitlist / "Get notified" / "Request early access" capture, or clearly labeled "Coming soon / Beta." If a real download is wired up later, this section gets updated and the CTA can change.

Treat §10 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.

---

11. Suggested site structure (for the website agent)

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

1. Hero — the one-liner, a sharp subhead, primary CTA (waitlist / early access), and a visual of the cockpit (dashboard with several sessions, a couple "needs you" badges).
2. The problem — the "you're the bottleneck / agents collide" framing from §2, kept tight.
3. The core idea — parallel worktree isolation, explained with a simple diagram: one repo → many isolated worktrees → many agents at once.
4. Feature showcase — lead with the ⭐ unique features (§5), each with a short headline + one-sentence payoff + a visual. The table-stakes features (§6) can be a denser grid below.
5. Mac + phone — the two-renderers story: cockpit on the Mac, approve-from-anywhere on the phone, E2E encrypted.
6. Trust & privacy — local-first, E2E encryption, real approval gating, sandboxed agents. This is a genuine differentiator; give it room.
7. How it works — the 5-step flow from §4.
8. Who it's for — §7.
9. 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).
10. CTA / footer — waitlist capture, repeated.

---

12. Voice, tone, and naming

• Name: Nucleic. The iPhone app is NucleicRemote. (The product was codenamed "Conductor" internally in early docs — do not use that name on the site.)
• 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 / conductor. "Nucleic" + "nucleus" + parallel "cells" of work is a fair visual/thematic well to draw from (sessions as isolated cells around a nucleus). Keep it subtle.
• Avoid: "magic," "10x," "revolutionary," "AGI," and any claim of full autonomy — the whole point is control. Don't promise the agent does it all unattended; promise you can run many and stay in command.
• Recurring proof-points to weave in: isolation (worktrees), parallelism (the dashboard), control (real approvals), reach (phone), trust (E2EE, local-first).

---

13. 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 and Codex 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."
• 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're not at your desk. Approve it from your phone, end-to-end encrypted, and keep the fleet moving."
• Autoship section: "Finished work, merged for you. Flip on Autoship and completed agents merge their own branch — safely queued, conflict-aware, never mid-task."
• 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 internal design docs (PLAN.md, RUNTIME_ARCHITECTURE, UX_MACOS, UX_IOS, BUILD.md) and the shipping codebase as of June 2026. When in doubt about a claim, prefer the capability that demonstrably exists over the roadmap item.