Adopt a repo brings a codebase into 1DesignTool: the app registers the
project on an app-owned worktree — a 1design/<slug> branch under your
app-data directory — so the agent designs inside your real UI without ever
writing to your checkout. It's the bridge from "design a thing" to "design in
my thing".
Adopting one
From the home screen, Open folder… picks the repo and opens the adopt
sheet: it reads the folder, asks whether to design inside it, and on
Design inside this codebase registers the project as a codebase project.
The app creates the worktree — a 1design/<slug> branch checked out under
app-data — and the project opens on that, not your checkout.
Your repo stays untouched: writes land in the app's worktree, reads come from your real files through it. The adopt sheet also shows the isolation note — what the worktree is and why your checkout isn't the working copy.
The worktree model
A codebase project lives on 1design/<slug> — a branch the app owns, checked
out as a worktree under app-data:
- Reads — the agent sees your real UI through the worktree
- Writes — turn diffs land on the branch, never your checkout
- Preview — the app's preview of the worktree, or your own dev server
- Your checkout — never written to; the host-managed paths (
.1design/, skill dirs) hide via.git/info/exclude, not your.gitignore
The branch bar on the project shows the lane — 1design/<slug> from main,
the commit count ahead, and the files the turns changed.
Designing inside the codebase
Once adopted, it steers like any project — but the brief is about your UI: "make the header sticky", "add a settings screen beside profile". The agent edits the real files through the worktree; the preview shows the app running on your own dev server or the app's preview.
The diff-scoped gate
Codebase projects don't run the full design-kit gate — your repo isn't a
generated artifact, so checking it like one would flag code the turn never
touched. Instead the checks are diff-scoped: the turn's changed files get
verified (tells.mjs on the diff), and the branch bar's review action shows
exactly what the turn did.
Review and merge
When a turn's work looks right, the branch bar's Review changes shows the
diff the turn produced; Copy merge command or Merge into main brings
the branch's work back to your repo. Discard throws the worktree state
away. Your checkout's main is what merges — the worktree is the sandbox.
Build and Sketch modes
A codebase project carries two extra modes on top of the live preview:
- Build mode — edit the running app's UI visually, and the changes write back into the code (see Build mode)
- Sketch mode —
.1dsketches that map to components (see Sketch mode)
Direct mode
The worktree model is the default because it's the safe one — the app writes to its own branch under app-data, never your checkout. Direct mode — the alternative on the adopt sheet — points the project at your checkout itself; the agent edits the real files in place. It's faster but the work lands on your working copy, so the worktree default exists for a reason.
What it's good at
- Designing inside your real app — the screen that already exists, restyled
- Feature work — a new screen or flow, in place
- UI passes — a whole-app visual pass, diffed
- Onboarding to the codebase — the agent reads the repo it has to live in
The isolation note
The worktree exists so the agent's work can't touch your checkout until you
merge — the registered project root is the app's branch, reads and writes go
through it, and the host-managed files the project needs hide via
.git/info/exclude so your git status stays clean. The cost is one step:
when the work's right, you merge the branch.
Tip: Keep the worktree until the merge is clean — deleting the branch before the work's confirmed costs the diff. The merge button makes it one action; review before you click it.