Step by step
Before you start
You need a terminal (this guide was walked on a Mac), Node 22 or later, Git, and the folder of a frontend project of your own. A Pen file is optional: HighFi works on code alone and shows every component as waiting for its design.
HighFi is in early access and its repository is private, so the install needs access first: ask Devin or Lenilson for access. Everything runs on your machine, and HighFi answers on this computer only: its terminal says so when it starts. To open it on a phone on the same network, start it with HIGHFI_LAN=1; anyone on that network can then read and change it. HighFi reads your project and never writes into it, and nothing is uploaded.
Install
There are two ways, and they end in the same place: HighFi in ~/highfi, running at http://localhost:5173.
With Claude Code. Copy the prompt on the Get started page and paste it into Claude Code. Claude checks Node and Git, clones HighFi over HTTPS, installs it with the same install script (told not to start HighFi, so it installs the app and writes the highfi command to ~/.local/bin), opens it, then asks for your frontend folder and your Pen file and opens HighFi on your project. It says what it is about to do before each step.
In the terminal. curl -fsSL https://www.highfi.dev/install.sh | sh does the install without Claude. It prints one line per step, each starting with highfi ·: cloning, installing the app, then how to start it next time (highfi when ~/.local/bin is on your PATH; otherwise the full path and the line to add to your shell, see the troubleshooting list) and starting: open http://localhost:5173 (Ctrl-C to stop). The script itself writes to ~/highfi and ~/.local/bin/highfi only. Once HighFi runs, it also keeps a small folder ~/.highfi (its start folder and the list of its windows). When you open Settings it asks the tools it finds, Claude Code and the GitHub CLI among them, for their sign-in state, to fill Connections; no other page runs them. The first time that happens with Claude Code installed and never yet run on this machine, Claude Code may write its own ~/.claude.json. Neither is in your project. The script clones over HTTPS, as the prompt does, and never asks for a password: a clone it cannot make comes back as one message that names both causes (see the troubleshooting list).
The install step downloads the app's packages and can take a few minutes the first time, longer on a slow connection. It is quiet while it works. Later starts take seconds.
First open
Open http://localhost:5173/app/ (the terminal prints the same place as http://127.0.0.1:5173/, and both open the same page). A new install has no project, so it opens on Start your first project with three doors: Bring your codebase, See your site first and Start from a starter. That empty page is expected.
Start from a starter makes, in the door's own words, a new git folder with a brand file and a setup plan; you add the components with the shadcn commands it lists. It does not come with a Pen file, tokens or components: the Pen file comes after those commands, so the Library reads 0 at first. Bring your codebase opens the New project dialog on Codebase, the same dialog the project menu opens; the next step goes through it. See your site first asks for a public address; in its own words, HighFi reads the pages anyone can open, from this machine, and ranks them by their links.
Your first project, without a Pen file
If you used the prompt, Claude has already done this: it made an empty Pen folder at ~/highfi-designs/<project name> and opened HighFi on your project.
By hand: choose the Bring your codebase door on the start page. Or open the project menu, the chip in the header that reads My projects › No project yet, and choose New project in My projects, then Codebase. Both open the same dialog.
Step one, where your work is: in Folder on this machine, type the path of your frontend folder, the one that holds your package.json, or put a public repository in GitHub address instead, not both. It is a text field, not a picker; a path that starts with ~ is read as your home folder. Project name may stay empty: the folder's own name is used. Leave Backend and Pen file as they are: with no Pen file, the frontend folder is the Pen folder. Press Scan: it only reads.
Step two shows what HighFi found, and nothing is imported yet: what it counted (components, screens, flows and tokens), the source and framework it detected, and How much to bring in first, from Core to All, the most linked and most used first. Its hours and agent runs are marked as a sample estimate. Press Confirm the plan. Step three asks where HighFi keeps its files, inside your repository or in a folder of its own; the one marked recommended is chosen, so press Continue. If you have not yet said how you use HighFi, a last step asks: Personal use is free and chosen; Commercial use takes a licence key. Press Start the import, then Open with your project's name on it.
Open moves the same browser tab to a second HighFi that HighFi starts for that project, on its own pair of ports: 5273 and 5278 for the first project, 5373 and 5378 for the next. It runs in the background, with no terminal of its own: 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. Without the highfi command, every highfi command in this guide also runs as npm run hf -- and the same words in ~/highfi/frontend-prototype-v1: here, npm run hf -- windows.
Your first project, with a Pen file
Pen is the design tool from pen.dev; a .pen file is your design. HighFi reads .pen files from one folder per project, the Pen folder: the folder your Pen file was already in when you gave it to the prompt, the folder you chose in New project, ~/highfi-designs/<project name> when the prompt made one, or your frontend folder when you left the field empty.
On the Settings page, the Paths group shows that folder in full, as Pen catalog (CATALOG_DIR). Save your design there, then tap Sync. A .pen file saved anywhere else is not read. While the project has no Pen file, the line under the pen.dev row in the Previews and design group prints the Pen folder in full, and so does the empty Library. When a .pen file 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 the file in place and never uploads it.
On a phone the empty Library shows the same message. Settings is reached from the project menu there, because the rail has no room for it, and it opens as a list of rows: tap Sources, Connections or Drivers to open the one long page that holds the Paths group and the Previews and design group.
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.
Read a drift row
Open Drift. Every component and screen is a row, and every row has a state in words, never a colour alone. There are thirteen states. The ones you meet first: Missing design (code exists, no Pen frame yet), Setup gap (a Brand field agents need is empty), Missing implementation (a Pen frame with no code), Code ahead and Design ahead (one side moved), Synced (both agree) and Unmapped.
On code alone, expect mostly Missing design, plus a few Setup gaps for the empty Brand fields. That is a true reading, not an error.
In a window 768 px wide or more, open a row to see its evidence: a small table with a Pen column and a Code column (file, hash, pixels, verified). A side that has nothing reads none for the file and the hash, so a row with no Pen frame shows none twice on the Pen side until you draw it; its pixels row reads not compared and its verified row never. The Pen and code pictures side by side appear once both sides exist.
On a phone there is no such table, on purpose. Tap a row and a sheet opens with the row's name, its state and one line saying what differs, above the actions. Tap the name to open the row's own page, which lists Score, Drift, Mean diff, Last verified, Hash and Signal. A row that has a Pen frame carries a link at the foot of that page, Open in with the place the row belongs to (Library for a component; Brand, Tokens or Screens for the others); a component's link lands on the Component view, where the comparison lives (Split, Wipe, Difference). A component or screen row with no Pen frame, which is every such row on a code-only project, has no such link: the route ends at the row's own page until the frame is drawn.
Two words in an open row need a line. Stand-in beside a hash or a verified date, and engine not connected, both mean the value is computed by HighFi's local server for now, in place of the checking engine that is not connected yet. Other words there, such as policy default, are not explained by this guide yet.
Fix one row with an agent, on mock drivers
HighFi starts on mock drivers: agents and pull requests are simulated, need no account and write a sample result, labelled sample.
A mock run works with no setup: HighFi clones your own folder, with no network, and branches from the branch you are on. 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 troubleshooting list).
Open a row, choose Resolve toward (Match Pen or Match code) and press Run agent. On a phone the sheet that opens has Resolve toward and Send to agent; Run agent is one tap further, on the row's own page (tap the row's name). When the run reads Ready for review, 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 folder, and nothing is pushed unless you press Push. On a row with no Pen frame, Match code writes a note for the Pen side, not code.
A mock run shows you the whole loop and fixes nothing: its result is a sample, so the row still reads as it did, Missing design for example, after you approve. A row changes when a real run, or you, changes the code or the design.
Real runs use Claude Code in place of the mock, with Claude Code installed and signed in. On Start or the Settings page choose Connect a harness, then Claude Code and Connect: that adds AGENT_DRIVER=claude to .env.highfi.local in HighFi's folder, and the next run in that window is real, with no restart. Every HighFi window reads that file when it starts, a project window opened from the project menu too.
Stop it, and open it again
Press Ctrl-C in the terminal that runs HighFi. That stops that HighFi only. A project window opened from the project menu keeps running in the background. highfi windows lists every HighFi window on this machine with its ports and its log, highfi stop 5273 stops the one on that app port, and highfi stop all stops them all. Without the highfi command, run npm run hf -- stop all in ~/highfi/frontend-prototype-v1.
To open it again: the command Claude gave in its summary opens your project directly. If you used the install script, highfi opens the empty start page; if you cloned by hand, npm run dev in ~/highfi/frontend-prototype-v1 does the same. From that page, open the project menu and choose Start on your project's row (it reads Open when that project's window is already running).
Troubleshooting
- The clone is refused. The script stops with "could not clone", and says that either you do not have access yet or git has no GitHub sign-in on this machine. Cause: One of those two. The repository is private in early access. And the script and the prompt both clone over HTTPS, so git needs a GitHub sign-in it can use over HTTPS; the script never asks for a password. What to do: No access yet: ask Devin or Lenilson for access. Access but no sign-in: sign in with gh, the GitHub CLI. If the
ghcommand is not found, install the GitHub CLI first:brew install ghon a Mac, or see cli.github.com. Then rungh auth login, choose HTTPS, and run the script or paste the prompt again. If gh is already signed in, rungh auth setup-gitso that git uses that sign-in, then try again. To clone over SSH instead, run the script with[email protected]:lenilsonjr/highfi.gitset. By hand:git clone https://github.com/lenilsonjr/highfi.git ~/highfi, thennpm ciandnpm run devin~/highfi/frontend-prototype-v1. - The script stops with "Node 22 or newer is not installed", or names an older Node. Cause: Node is missing or older than 22. What to do: Install Node from nodejs.org (22 or later), open a new terminal and run it again.
- The script stops with "exists and is not a HighFi checkout". Cause:
~/highfialready holds something else. What to do: Move that folder, or setHIGHFI_DIRto another folder and run the script again. - The install seems to hang after "installing the app". Cause: It is downloading the app's packages, and prints nothing while it does. On a first run it can take a few minutes. What to do: Wait. If it ends with
npm ci failed, check your connection and run it again. - npm prints vulnerabilities after an install by hand. Cause: A plain
npm ciprints npm's audit summary. It is a notice about packages, not a failed install. What to do: Nothing. The prompt and the script install withnpm ci --no-audit --no-fund --loglevel=errorso the notice does not appear. highfi: command not found. Cause: The script puts the command in~/.local/bin, which is not on the PATH of a default macOS shell. What to do: Run it by its full path,~/.local/bin/highfi. To type justhighfi, add the line the script prints to~/.zshrc(or~/.bashrc) and open a new terminal:export PATH="$HOME/.local/bin:$PATH".highfianswers "unknown command" and starts nothing. Cause: The first word afterhighfiis not one of its commands, so the launcher treats it as a typo. What to do: Runhighfiwith no argument to open the app, orhighfi --helpfor the commands (windows, stop, import scan and the rest).- HighFi stops and says "Port 5173 is already in use, so the app cannot open there". Cause: Another HighFi window or another program holds the port. HighFi needs 5173 for the app and 5178 for its file API, and stops rather than move to another port. When it is the file API's port, the sentence says the file API cannot start there. What to do: Stop the other one:
highfi windowslists HighFi's windows, andhighfi stopwith an app port stops one. Or start again on a free port: setWEB_PORTwhen the sentence names the app,PORTwhen it names the file API. Project windows use their own pairs: 5273 and 5278, then 5373 and 5378. - The start log says "not listed in highfi windows". Cause: HighFi keeps a list of its windows in
~/.highfi, and at start each HighFi says in one line when it is not on that list, and why. Two of the reasons need you. One:another HighFi (pid N) already holds app port 5173, so this one has no app address of its own. It still answers on its file API as usual, but the project menu andhighfi windowswill not show it andhighfi stopwill not stop it. Two: the list filecould not be opened, so this HighFi leaves it as it is and runs unlisted. It looks again every 30 seconds by itself. What to do: For the first, start it again withWEB_PORTset to a free port, as the line says, and stop this one with Ctrl-C in its terminal. For the second, the line endscheck that this account may read that file: check that your account may read the file it names. A line that saysnot listed in highfi windows yetneeds nothing: that HighFi runs as usual and tries again by itself. - The app opens on an empty start page. Cause: A new install has no project. What to do: Choose Bring your codebase or Start from a starter, or run the open command the prompt gave.
- Views stay empty or show an error, and the Sync control in the rail shows a pill reading offline. Cause: The file server is not answering.
npm run devstarts it together with the app. What to do: Read the lines markedserverin the terminal. A project window has no terminal: Settings, Sources shows the path of its log, andhighfi windowsprints it too, beside both of its ports (data/projects/<project id>/window.login~/highfi/frontend-prototype-v1). - The starter project has no Pen file and the Library reads 0. Cause: That is what the starter is: a new git folder with a brand file and a setup plan. The dialog says so before you create it: the Pen file is pending, and the components come from the shadcn commands the plan lists. What to do: Follow the setup plan (the dialog says it is in Agent Q), or use Bring your codebase on a project you already have.
- You saved a Pen file and HighFi shows nothing for it. Cause: It is not in the Pen folder, or HighFi has not read the folder again. HighFi reads
.penfiles from one folder per project, and a file in your frontend folder is not read when the Pen folder is another one. What to do: The empty Library and the Paths group on the Settings page print the Pen folder in full, and both name a.penfile found in your frontend folder. On a phone, Settings is reached from the project menu: tap Sources. Move or save the file into the Pen folder, then tap Sync. - Drift has no rows. Cause: The scan read a folder that holds no app. What to do: Point New project at the app's own folder, the one that holds its
package.json. - Every row reads Missing design. Cause: There is no Pen file in the Pen folder yet, so every component and screen found in your code waits for its design. What to do: Nothing is wrong. Draw the frames in Pen, or send a row to an agent.
- An agent run sits on Prepare worktree for up to 90 seconds. Cause: 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; its log then says that the address "did not answer for 90 s; HighFi stopped waiting and cloned your own folder" in its place. What to do: Wait: the run continues by itself. To use the remote, check the address (CLONE_URL) and your network.
- A run stops and says your folder is not a git repository. Cause: An agent works on a branch, so it needs a repository to branch from, and your frontend folder has none. What to do: Run
git initin your frontend folder and make a first commit, then send the row again. AGENT_DRIVER=claudeis set and runs are still mock. Cause: A window reads.env.highfi.localwhen it starts, and Connect reads it again only in the window you pressed it in. A window that was already running keeps the mock driver. A value set in the environment HighFi was started with wins over the file, an empty one too. What to do: Stop that window and open it again:highfi windowslists them,highfi stopwith its app port stops one, then open the project from the project menu. Or press Connect in that window. Start HighFi withoutAGENT_DRIVERin its command unless you mean it. 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.- After copying
.env.exampleto.env, the Start page is gone. Cause: A.envfile tells HighFi it is set up, so the first-run Start page no longer shows. A.envcopied from an older example may also setBASE_BRANCH=production, which replaces the branch HighFi takes from your folder. What to do: You do not need the file: every value in it has a working default. Remove the.envyou made. For real runs use Connect a harness, which writes.env.highfi.localand leaves the Start page as it is. - Ctrl-C did not stop the project you were looking at. Cause: It stops the HighFi in that terminal only. A project opened from the project menu is a second HighFi in the background. What to do: Run
highfi windowsto see every HighFi window with its app port, thenhighfi stop 5273with that port, orhighfi stop all. npm run test:unitends with a list headed failing tests. Cause: That list holds three known problems marked todo, and the run passed: read the fail count above it. What to do: Read the line that startsfail: 0 means the install is sound.- Still stuck. Cause: Something this page does not cover. What to do: 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 happen.