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