The guide

How NerfedLab is meant to be used.

Surface by surface, current as of version 6.7. Everything here exists and runs; nothing is aspirational.

1. What NerfedLab is

NerfedLab turns a plain language product description into designed screens, then into a real, running app, on your machine, through the subscription you already have. No API keys, nothing billed beyond it. Projects live locally under ~/.nerfed; every project’s workspace is a real git repository with automatic history.

Describe it in the chat → answer a few question cards → watch the screens draw themselves
→ Start the build → the built app IS the canvas, running in the App view and on your phone
→ iterate by chatting, or edit the code directly
→ on a product with a GitHub repo: a draft → the smoke test → send for approval
   → the review on the pull request → Ship vN → roll it out by percentage

One studio, always the full one. There is no simple mode to switch out of.

2. First launch

1. Sign in. The welcome screen offers Continue with Google. Two checkboxes sit under it: anonymous usage stats (off unless you opt in) and crash reports (on by default).
2. Connect the engine. NerfedLab drives the Claude Code CLI. The next step checks for it, shows the install command when it is missing (the app can run the install in its own terminal), and waits until claude answers. If the CLI is missing or signed out later, an amber banner appears above the studio and routes you back here. Nothing generates until the engine is connected.
3. That is it. The home screen is next.

3. The home screen

A full width dashboard of your projects.

• The dotted + tile creates a blank project called Untitled and opens its studio. There is no prompt box: the first message you type in the chat is the kickoff. It names the project and starts the design.
• Import from GitHub is the other doorway. Connected, pick from your repositories, private included; not connected, paste any public one. A project that was published or backed up from NerfedLab comes back whole, with its name, settings, design, drafts, versions and chat history. Any other repository becomes a product whose memory the agent builds on first open. Importing the same repository twice offers the existing project instead.
• Each project tile carries its facts: the live version and how many drafts are in progress. A product on GitHub opens on its Branches home; a plain project opens in the studio. Nothing is ever deleted on its own.
• Back up all backs every project up to its own private GitHub repository, as a full restore point. It says so before it runs.
• Connect, in the same header, is the setup for your other tools: this NerfedLab’s MCP endpoint and token, one click for VS Code and Cursor, a command for Claude Code, a config block for Claude Desktop, Codex and any other MCP client.

4. The studio

Opening a project lands you in the studio.

• The titlebar shows the project name and your account, with Open in VS Code and Connect beside them.
• The ladder strip under it appears on a draft or when a release exists: the change’s place, step by step, with the verbs that can run right now.
• The rail on the left: Design (the chat and the canvas), Design system (the tokens), Preview (the design as a page), App (the built app, running), Memory (once any document exists), Release (once a version is armed), Git, Modules, Files, VS Code, and Terminal.
• Inspection. On a product, main is read, never worked on: the studio shows only Design system, Memory, Release, Git and Files, with a banner offering a new draft. A draft that already merged is frozen the same way, with a Follow up draft button.

5. The chat

The chat is a live agent session scoped to the project’s workspace. It is how you design, build and change anything.

The strip at the top

• The model picker. Switching is instant.
• Permissions: auto-edits approves file edits and the build toolchain; bypass all runs every tool without asking; plan is read only.
• QC: when on, a design turn runs one quality pass after writing.
• The context meter: how full the session’s context window is.

What appears in the transcript

• Question cards. Option chips, multi select where it fits, a free text field. A question marked as a secret masks its field; the value goes to the workspace’s .env.local and the agent sees only that it was stored.
• One live thinking line. The agent’s latest thought, never a wall.
• Teammates. When the build fans out, each teammate is a chip with a name.
• Phase chips. “Screens · 2 of 5”, “Sync · 4 of 7”: one chip that updates in place.
• The plan chip. After a build is planned, the chip carries Start the build. Nothing is built until you press it.
• App updated, APK ready. A turn that changed real code, with a jump to the App view; a packaged Android build with its download.
• The smoke card and the Review card. Sections 11 and 12.

Typing. Enter sends, Shift+Enter is a newline, / opens the CLI’s own commands. A message typed while the agent is mid turn waits its turn and sends when the turn ends.

Design first. A request for a new feature, flow or screen is a design request: the agent draws the new or changed screens and stops. Code runs only when you say “build it” or press Start.

If things go quiet. A banner appears when a turn is active but nothing has arrived for a while. Reconnect re syncs the transcript; a genuinely stuck agent is replaced and picks your last message back up.

6. Design

The canvas renders the screens as the agent writes them: each element reveals as it lands, and the design’s name becomes the project’s name. A bar along the bottom lists the screens; on a draft, the screens the draft added carry a draft tag.

• Navigate: scroll or drag to pan, hold Space for the hand, ⌘ plus and ⌘ minus to zoom, 0 fits everything.
• Tools: V select, H hand, F frame, T text, R rectangle.
• Inspect: click any element for the layers panel and the properties panel.

Design changes go through the chat (“make the hero full bleed”, “add an onboarding screen”). The canvas re renders live as the agent edits design.json.

7. Build

Building is two stages, on purpose.

1. The plan. Ask to build it, or press Build in the App view. The agent asks one technical card, recommends a stack, and lays out a three phase plan. It cannot write files in this stage. The plan ends with “Press Start the build below when you are ready.”
2. Start the build. The design is lifted one to one into an app shell first (sections per screen, the design’s fonts, navigation between screens), committed, and then the agent adds behavior. It never redraws or restyles a screen.

The handoff. On a project’s first successful build the app stacks into a phone in front of you. Preview on phone serves the app on your network and shows a QR code; until you opt in, the served app is reachable only from this machine.

The App view manages one live instance of the app: Nothing to run yet with Build this design into an app; Built app not compiled yet with Install deps and build; Building your app with the live feed; Running, with Reload, Open in browser, Stop, and a Live link once the app is on GitHub Pages; The app didn’t start with the error and Fix this, which hands the exact error to the agent. A rebuilt app shows a Restart chip.

Take it to your phone. The phone icon packages the running app as an installable Android APK (Capacitor plus gradle; Android Studio brings the tooling). The chat gets an APK ready chip with the download.

8. Memory

A product remembers itself in seven short documents under memory/: architecture, code map, design system, conventions, data model, the sensitive map, decisions. The Memory tab appears once any of them exists.

• On a NerfedLab origin repository the sync runs on its own when the Branches home opens; on a foreign repository a button offers it. Drafts unlock when all seven documents exist.
• On a new project the design skill writes the design system document after the first card and appends your preferences to decisions.
• The product itself records what it knows for certain: a decision you made on a question card, the first build, the version each Ship shipped.

9. Products on GitHub: the Branches home

A project with a GitHub repository (imported, published or backed up) is a product. It opens on its Branches home, not the studio.

• main is the first tile: what is live, with its version and mini artboards.
• Drafts are tiles: in progress, or merged once shipped (“Shipped as v3. Frozen; a follow up starts from the + tile”).
• The + tile creates a draft: type a name, Enter. It stays locked until the memory sync is done.
• Every draft starts from main and is a session of its own: the chat starts with “New session on draft, project memory loaded”. Switching back to a draft resumes its own conversation.
• A merged draft is frozen. Its studio is read only, with the banner Shipped as vN and Follow up draft.

10. The ladder

The strip under the titlebar reads the change’s place from real state, never from narration:

Draft › Smoke test › Sent for review #N › Code review › Security review › Merged · vN › Rolling out N%

• Smoke test: pending, failing, green, or stale after a new commit.
• Sent for review #N: the pull request, linked. Without GitHub connected it reads “connect GitHub to see”.
• Code review: waiting, commented, changes requested, approved, or approval reset by a new commit.
• Security review: clean, or N findings and blocked.
• Merged · vN, then Release · vN · armed 0% or Rolling out · N%.

The verbs on the strip: Run the smoke test on a changed draft; Send for approval once the smoke test is green on this tip and GitHub is connected; Ship vN once the smoke test is green, the security pass is clean and no change request is open; Review opens the Review card whenever a pull request exists or the pass found something. The routes refuse what the strip would not offer, and each refusal says what to do next.

11. The smoke test

Seven checks over the draft’s served app: the build, the server, the code checks, every screen present, a clean console, Back working, and no dead controls (a painted control that does nothing, or one covered by another element, is named). The verdict is about a commit: a new commit makes it stale, and it runs again with a pull request open.

The card in the chat shows each check as it lands. Red: Fix these hands the findings to the agent, then run it again. Green: the card carries the next verb, Send for approval or Ship vN. The latest verdict comes back into the chat when you reopen the project.

12. The review

The pull request is the review.

• Reviewers. In the Git view’s GitHub section, type the GitHub logins who review this project’s changes. Every pull request the project sends asks them on GitHub; the author is never asked.
• Send for approval pushes the draft, opens the pull request, asks the reviewers, and posts the automated security pass as a comment.
• The security pass runs over the draft’s diff against main: a credential in a URL query string, a secret behind a public build variable, a hardcoded credential, plus the paths the project’s sensitive map and the classifier call risky. It blocks only what it is sure of: a lookup key in a URL, a public browser key or a design token named “token” are notes on the card, not blocks.
• The Review card in the chat mirrors the pull request: the reviews, the code comments, the conversation, and the pass with every finding’s file, line, reason and fix. Make it safe hands the findings to the agent; Address the review hands the reviewers’ words to the agent; the reply box posts on the pull request as you.
• An approval is about a diff, not a branch. A commit after an approval resets it. A change request holds Ship until it is answered.

13. Release

Ship arms a release at 0%: it exists, nobody sees it. The Release view appears once the built app carries the rollout runtime and a shipped version armed a config.

• The slider (0, 10, 25, 50, 100) writes and commits rollout.json; the running app polls it and flips its own cohort membership live, no reload.
• The cohort grid shows ten real devices through the app’s own hash: who sees the release at this percentage.
• Target this device is the override: this device sees the release at any percentage.
• Guardrails count real beacons from the running app. Three cohort errors against a quiet baseline halt a live ramp on their own; a ramp clears the halt.

14. Git

• Drafts. A new draft from the input (always cut from main), the list to switch, delete.
• History. Every agent turn commits with your prompt as the message. Restore any commit as a new forward commit, never a rewrite.
• Ship as vN on main tags what is live. A draft ships from the ladder strip, where the gates are.
• A risk badge on a draft names what its diff touches (auth, payments, schema, infrastructure, dependencies, the sensitive map’s paths).
• GitHub. Connect through GitHub’s device flow; the token stays encrypted in the OS keychain. Then Publish (a private repository by default), Sync, Back up to GitHub, Go live (the static build on GitHub Pages), the reviewers row, unlink and disconnect. The mirror is one way: NerfedLab is the source of truth.

15. Files, Modules, VS Code, Terminal

• Files is a real editor over the workspace. ⌘S saves. ⌘⇧F searches the project, with Replace all. TypeScript files check as you type; hover shows types, ⌘ click or F12 jumps to a definition, F2 renames across the project. Select code and press ⌘K to ask the agent for an inline edit; the result comes back as a diff to accept or reject.
• Modules is the workspace’s module map.
• VS Code runs the editor itself, extensions included, on this project’s workspace. The first time, it asks to install VSCodium’s server (about 125 MB, MIT); extensions come from Open VSX. One editor server runs for the whole of NerfedLab, on this machine only.
• Terminal is a shell rooted in the workspace.

16. Connect your tools

NerfedLab is an MCP server. Connect (the home screen’s header, or the studio titlebar) shows the endpoint, the token and the setup for each client:

• VS Code: Add to VS Code, or the code --add-mcp command. Copilot agent mode, Cline, Continue, the Claude Code extension and every other MCP aware extension can then drive NerfedLab.
• Cursor: Add to Cursor.
• Claude Code: one claude mcp add command.
• Claude Desktop: paste the block; it runs a small bridge that finds NerfedLab on its own.
• Codex and anything else that speaks MCP: the config block or the raw URL and header.

A connected client can do everything the studio does, by the same rules. GitHub verbs act as you only if you switch on Let connected clients use my GitHub. The token is the key to this NerfedLab: keep it to yourself, rotate it if it leaks.

17. Under the hood

• Your subscription, your machine. Every AI turn runs through the engine on your own Mac (Claude Code out of the box; the subscriptions your company chooses in a company setup). No NerfedLab API keys, no server side generation.
• Data lives in ~/.nerfed/projects/; the workspace inside is a normal git repository. The MCP token and VS Code’s server live in the same root, never inside a workspace.
• The served app binds to this machine only until you choose Preview on phone.
• Updates. The app checks at launch, downloads in the background, and installs when you quit.
• Privacy. Crash reports are on by default, usage stats off unless you opt in. Neither includes your code or designs. Your GitHub token never reaches NerfedLab’s servers.

18. Troubleshooting

A question this guide does not answer is a bug in the guide. Write to hello@nerfedlab.com.