Meet the harness

We've changed a heading ourselves. Now we'll ask fx to inspect the same project and explain where a larger edit belongs. Before it changes any files, we need to know which folder it can see and how it asks to use tools.

In the website folder, check our starting point:

cd ~/projects/small-hours-studio
git status

The working tree should be clean after the previous lesson. If something has changed, inspect it before starting the agent so we can distinguish our existing work from anything it does.

Outcome

Install fx, sign in through Vercel AI Gateway, and use it to explain the workshop project without editing it.

Hands-on exercise 3.1

Install the course version

fx is an open-source coding agent harness: software that gives an AI model access to tools such as reading files and running commands. The model proposes actions; the harness carries them out under its permissions. It can use different models, so its behavior also depends on the selected model.

This course uses public release v0.0.10. fx is experimental, and later versions may change commands or menus. On macOS or in the Ubuntu WSL terminal, run the version-pinned installer:

curl -fsSL https://fx.sh/setup.sh | bash -s -- v0.0.10

This downloads the official installer and runs it with Bash. The version argument selects our release. Review the installation instructions before running it if installing command-line software requires additional steps on your computer.

Follow the installer's PATH instructions, or open a fresh terminal, then check:

fx --version
fx --help

The public macOS release checked for this course reports 0.0.10. The help lists commands available in that installed version. Keep that output as the reference if online documentation describes a newer feature.

Sign in and check costs

We'll use Vercel AI Gateway as fx's model provider. Requests can cost money, so check the selected team's balance and model pricing before the first request. A v0 subscription doesn't cover unlimited fx usage.

From the shell, start the browser sign-in:

fx login
fx credits

Complete Vercel authentication in the browser and return to the terminal. Check that the account and team are the ones intended for this course. The authentication guide covers team selection and alternate setups. Keep tokens and account credentials out of prompts and project files.

After a session, fx usage reports usage recorded on this computer. Use the team's AI Gateway dashboard for provider-side totals. The usage guide explains that distinction; local usage may not include another device's requests.

Enter fx

Move into the project if the new terminal opened elsewhere, then start the interactive interface:

cd ~/projects/small-hours-studio
fx

We are now typing inside fx. A sentence entered here is an agent request. A command such as git status belongs in the shell unless we are deliberately asking the agent to run it. Use a second terminal when we need to run our own commands during a session.

Inside fx, set the permission mode:

/permissions ask

In this mode, fx asks us to review sensitive tool calls unless an existing rule or permission already allows them. Ordinary project reads may proceed directly. Inspect the action and its scope when a prompt appears; a broad saved permission can affect later requests. See the permission guide for how rules and modes interact.

Ask for a project map

Enter this request inside fx:

Read this workshop website and explain how its homepage is built.
Find the homepage, shared layout, workshop data, and card component.
Name the actual file paths and explain how they connect.
Do not edit files, install dependencies, read credential files,
commit changes, or deploy. Keep the explanation brief.

Check fx's explanation in the editor against the files we explored in 2.4. If it names a missing file, ask it to show the source it used.

Try It

Open one file fx identified and find the heading or workshop title it described. Then ask which file would let us show a duration label on every card. The reference answer involves components/workshop-card.tsx; a generated project may organize it differently.

Exit the interface with /quit. At the shell prompt, run git status again. The working tree should remain clean. Run fx usage to inspect this session's recorded usage.

The shell cannot find fx

Open a new terminal after installation and check the installer's PATH guidance for ~/.local/bin. On Windows, run the command inside the same Ubuntu environment where we installed it. Installing into one environment doesn't make the command available in every terminal.

Authentication works, but the request fails

Check the selected provider, team, and available credits. Use /status inside fx and the account dashboard. A billing or model-access problem needs to be resolved before retrying; changing the project code won't fix it. Avoid repeated requests while the underlying account issue remains.

Commit

This exercise should produce no application changes. Record the fx version and the file paths it identified in your course notes. If Git shows changes, inspect them and find their cause before continuing.

Done-When

• The installed version and help commands run successfully.
• The intended account has access to the selected model and its usage costs are understood.
• fx identifies the homepage and workshop card using existing files.
• The session ends with the application's working tree unchanged.

Solution

The project map in the reference app is:

Use the inspection prompt above, verify these relationships in your generated project, and leave fx with /quit. We'll use those file paths to give fx its first editing task.