Onboarding · about 15 minutes

Get started on your machine

HighFi runs locally. You need Node 22 or later, Git and your frontend repository, and Pen (the design tool at pen.dev; a .pen file is the design) for the design side; your Pen file too, if you have one. HighFi sends nothing on its own: no account, no tracking. Your code leaves your machine only when you choose: a coding agent you connect reads it to do the work you send it, and a pull request you open goes to your own GitHub. A site scan visits the pages of the site you name. The first site scan also downloads a page reader, Chromium, once from Playwright's servers.

Paste one prompt into Claude Code

Copy this prompt and paste it into Claude Code. Claude checks Node and Git, installs HighFi into ~/highfi, opens it at localhost:5173, then asks for your frontend folder and Pen file and opens HighFi on your project. It never writes into your repository. HighFi is in early access, so the repository is private for now: ask Devin or Lenilson for access first.

Works in Claude Code, and in any Claude environment that can run commands.

Please install HighFi on this machine, open it, and point it at my frontend project. HighFi is a local app that shows where my built frontend and my Pen design file (Pen is the design tool at pen.dev; a .pen file is the design) have drifted apart (the design and the built app no longer match). Tell me in plain words what you are about to do before each step, and stop and ask me if anything fails.

Rules for the whole task:
- Never write into my own project repository. HighFi lives in ~/highfi; my project is only read.
- Never open or read the contents of my .pen files; only pass their folder path to HighFi.
- Never print secrets, tokens or the contents of .env files.
- Do not install anything system wide without asking me first.

Steps:
1. Check that Node 22 or later and git are installed (node --version, git --version). If either is missing or Node is older than 22, tell me how to install it and stop.
2. If ~/highfi is already a git checkout, update it with git -C ~/highfi pull --ff-only. Otherwise clone it: git clone --depth 1 https://github.com/lenilsonjr/highfi ~/highfi. HighFi is in early access and the repository is private for now; if the clone is refused, tell me to ask Devin or Lenilson for access (or, if I already have access but git has no GitHub sign-in, to run gh auth login and choose HTTPS; gh is the GitHub CLI, and if that command is not found, to install the GitHub CLI first, with brew install gh on a Mac or from cli.github.com; or, if gh is already signed in and the clone is still refused, to run gh auth setup-git first, so that git uses that sign-in), then stop.
3. Install the app with HighFi's own install script, without starting it: HIGHFI_NO_START=1 sh ~/highfi/site/install.sh. Tell me first that it installs the app's packages and writes one file, the highfi command, to ~/.local/bin in my home folder (not system wide). When that folder is not on my PATH, the script prints the line to add to my shell: pass that line on to me. It can take a few minutes the first time.
4. Start it in the background: npm run dev in ~/highfi/frontend-prototype-v1, so it keeps running while we talk. Wait until http://localhost:5173 answers, then open http://localhost:5173/app/ in my browser. Tell me it opens empty, on a start page with three doors (bring my codebase, see my site first, or start from the shadcn starter), and that my own project comes next.
5. Ask me two things: the full path to my frontend project folder, and the path to my Pen file (optional; I may not have one yet). Check the frontend folder exists. If I give a Pen file, use the folder it is in. If I have none, create an empty folder at ~/highfi-designs/<project-name> and use that.
6. Open HighFi on my project with the same command its New project flow gives. Stop the HighFi you started in step 4, then run this in the background, filling in my values (project name defaults to my frontend folder's name; project id is that name in lowercase with hyphens; the team is mine, the id of My projects):
   cd ~/highfi/frontend-prototype-v1 && PROJECT_NAME="<project name>" PROJECT_TEAM="mine" CATALOG_DIR="<Pen folder>" FRONTEND_DIR="<frontend folder>" DATA_DIR=data/projects/<project id> npm run dev
   When http://localhost:5173 answers again, open http://localhost:5173/app/ and tell me to open Drift: every component and screen HighFi found in my code is a row with its state in words.
7. Finish with a short summary: where HighFi is installed, the Pen folder HighFi reads (the folder I save my .pen file in once I have one), the exact command to open my project again next time, and how to stop it.
For a new Claude Code session, in any folder.

Prefer the terminal? This does the install without Claude: it clones HighFi into ~/highfi, adds a highfi command and opens the app. You can read the script first; it writes only to ~/highfi and ~/.local/bin/highfi. Once HighFi runs, it also keeps a small folder ~/.highfi (its start folder and the list of its windows), and the first time you open Settings with Claude Code installed, Claude Code may write its own ~/.claude.json. Neither is in your project.

curl -fsSL https://www.highfi.dev/install.sh | sh

Start your first project

The app opens empty, on a start page with three doors: Bring your codebase, See your site first or Start from a starter. A starter makes a new folder with a brand file and a setup plan, and lists the shadcn commands to run in it (npx shadcn@latest init downloads from the internet); its Pen file and components come after those steps, not with the click. This guide follows Bring your codebase. To see HighFi on real projects first, open the live demo on this site. Prefer to do it by hand? git clone https://github.com/lenilsonjr/highfi.git ~/highfi, then npm ci and npm run dev in ~/highfi/frontend-prototype-v1.

In the live demo: New project with Starter pack chosen. The demo holds no starter pack, so its dialog says there is none to install. A fresh install offers the same three doors on its start page.
In the live demo: New project with Starter pack chosen. The demo holds no starter pack, so its dialog says there is none to install. A fresh install offers the same three doors on its start page.

Install Pen and connect it

HighFi compares your code with your design, and the design lives in Pen. Install the Pen app from pen.dev, open your Pen folder in it and save your design there as a .pen file. Your Pen folder is the one HighFi reads .pen files from: the folder the prompt made for you (~/highfi-designs/<project name>), the folder your Pen file was already in, or your frontend folder when you left the Pen field empty in New project. On the Settings page, the Paths group shows it in full, as Pen catalog (CATALOG_DIR). While the project has no Pen file, the empty Library prints it in full, and so does the line under the pen.dev row in the Previews and design group. A .pen file saved anywhere else is not read; if one sits in your frontend folder instead, the empty Library and the note at the foot of the Paths group name it and say to move it. HighFi reads that file in place and never uploads it. The same page lists what HighFi found on this machine, one row each with its state and the step left: Connections has Claude Code, GitHub, Codex and the CLI and agents row; Previews and design has Vercel and pen.dev.

Settings in the live demo: Connections lists Claude Code, GitHub, Codex and the CLI and agents row, and Previews and design lists Vercel and pen.dev, each row with its state. On a phone the picture starts at Previews and design. The paths of the recording machine are blurred.
Settings in the live demo: Connections lists Claude Code, GitHub, Codex and the CLI and agents row, and Previews and design lists Vercel and pen.dev, each row with its state. On a phone the picture starts at Previews and design. The paths of the recording machine are blurred.

Onboard your codebase

The prompt does this for you. By hand: in the project menu choose New project, then Codebase. Point it at your frontend checkout, and at your Pen folder if you have one (leave it empty to read .pen files from the frontend folder). Scan counts components and routes and shows an import roadmap by prominence. Choose Open when the project is created, or pick it later in the project menu: HighFi opens it in the same browser tab, starting a second HighFi for it the first time, on its own pair of ports (5273 and 5278; the next project gets 5373 and 5378). That second HighFi runs in the background with no terminal: Settings, Sources lists the HighFi windows by their app port, and shows the path of the log for a window that has no terminal; highfi windows in a terminal prints each window with both its ports, its project and its log, and highfi stop all stops them (the help list below has the details). HighFi never writes to your checkout; agents work in a clone.

New project, Codebase: a folder on this machine or a GitHub address, an optional backend and Pen file, then Scan.
New project, Codebase: a folder on this machine or a GitHub address, an optional backend and Pen file, then Scan.

Read your first drift

Open Drift. Every row has a state in words (for example synced, code ahead, design ahead, missing design, missing implementation, unmapped and setup gap; there are thirteen in all) with its evidence. No Pen file yet? Every component and screen HighFi found in your code is a row, missing design, ready to draw in Pen or to send to an agent, and empty Brand fields show as setup gaps. Open a row to see its evidence: what the Pen side and the code side hold (the Pen side reads none until you draw it) and, once both exist, the Pen and code side by side.

Drift in the live demo has 39 rows: components, screens, tokens and four system rows, each with its state in words. Your first drift shows your own rows, mostly missing design.
Drift in the live demo has 39 rows: components, screens, tokens and four system rows, each with its state in words. Your first drift shows your own rows, mostly missing design.

Fix one row with an agent

Open a row, choose Resolve toward (Match Pen or Match code) and press Run agent. Mock runs (agents and pull requests are simulated until AGENT_DRIVER and PR_DRIVER are set) need no account and write a sample result, labelled sample. They need no setup: HighFi clones your own folder, with no network. If your project names a repository this machine cannot reach, the run sits on Prepare worktree until HighFi stops waiting, 90 seconds without an answer by default, then goes on from your own folder (see the help list). On a row with no Pen frame, Match code writes a note for the Pen side, not code. When the run is ready, the row shows its diff with Approve commit, Push and open draft PR and Discard: approving commits in HighFi's own clone, never in your checkout, and nothing is pushed unless you press Push. For real runs, choose Connect a harness on Start or the Settings page, then Claude Code and Connect, with Claude Code installed and signed in: it adds AGENT_DRIVER=claude to .env.highfi.local in HighFi's folder, which every HighFi window reads when it starts. On the Settings page, Drivers shows which drivers this HighFi may use, and the Claude Code row under Connections shows whether it is signed in.

A row opened in the live demo: the evidence table with its Pen and Code columns, the Pen picture, and Resolve toward. This row has no app capture. On a phone the picture is the sheet a tapped row opens, with Resolve toward and the actions.
A row opened in the live demo: the evidence table with its Pen and Code columns, the Pen picture, and Resolve toward. This row has no app capture. On a phone the picture is the sheet a tapped row opens, with Resolve toward and the actions.

Tell us what happened

Early access is how we learn. Note where you got stuck, what you expected and what HighFi said, and send it to Devin or Lenilson. Every note shapes this guide and the product.

If something goes wrong
  • The clone is refused. HighFi is in early access and the repository is private. Ask Devin or Lenilson for access. If you have access but git has no GitHub sign-in on this machine, sign in with gh, the GitHub CLI. If the gh command is not found, install the GitHub CLI first: brew install gh on a Mac, or see cli.github.com. Then run gh auth login, choose HTTPS, and paste the prompt again or run the install script again: both clone over HTTPS. If gh is already signed in, run gh auth setup-git so that git uses that sign-in.
  • It says Node is missing or too old. Install Node 22 or later from nodejs.org, open a new terminal and run it again.
  • A port is already in use. HighFi needs port 5173 for the app and 5178 for its file API, and stops rather than move to another port. The terminal says so in one sentence: Port 5173 is already in use, so the app cannot open there: another HighFi window or another program holds it. Stop the other one (highfi windows lists HighFi's windows), or start again on a free port: set WEB_PORT when the sentence names the app, PORT when it names the file API. A project window opened from the project menu uses its own pair: 5273 and 5278, then 5373 and 5378.
  • The app opens on an empty start page. That is expected. A new install has no project until you choose Start from a starter or Bring your codebase, or run the open command the prompt gives.
  • Views stay empty or show an error. The file server on 5178 is not answering, and the header says Sync offline. npm run dev starts the file server and the app together; check its terminal for the lines marked server. A project window opened from the project menu has no terminal: Settings, Sources shows the path of its log (data/projects/<project id>/window.log in frontend-prototype-v1), and highfi windows prints it too.
  • Drift has no rows. Check that the frontend folder is the one that holds your package.json; in a monorepo, the app's own folder (at the repository root the scan can read the project as plain HTML). With no Pen file yet, every row reads missing design, which is expected.
  • An agent run sits on Prepare worktree for up to 90 seconds. Your project names a repository this machine cannot reach, and HighFi tries it before your own folder. It stops waiting after 90 seconds and the run goes on by itself; its log then says that the address "did not answer for 90 s; HighFi stopped waiting and cloned your own folder" in its place. To use the remote, check the address (CLONE_URL) and your network.
  • How do I stop it, or open it again? Press Ctrl-C in the terminal that runs it. That stops that HighFi only: a project window started from the project menu runs in the background with no terminal. highfi windows lists every HighFi window on this machine with its ports and log, highfi stop all stops them all and highfi stop 5273 stops the one on that app port (without the highfi command, run npm run hf -- stop all in ~/highfi/frontend-prototype-v1). To open it again, run highfi if you used the install script (the installer prints the full path when ~/.local/bin is not on your PATH; highfi opens the empty start page, so pick your project in the project menu), or run the command Claude gave in its summary, which opens your project directly.
  • Still stuck. Copy the last 20 lines of the terminal, check they hold no tokens or keys, and send them to Devin or Lenilson with what you expected. To check the install itself, run npm run typecheck and npm run test:unit in frontend-prototype-v1: both finish without an error. test:unit ends with a list headed failing tests that holds three known problems marked todo; read the fail count above it.