Start a PathMX project

You set up your computer, then hand this page to Claude. When you're done you'll have your own PathMX project running on your computer, a change you made to it with Claude, and a short setup report to send Mark.

You do the installs and sign-ins. Claude does the building and checking, and asks before anything that needs you. Allow about 45 minutes.

Part of the point of the club is finding where PathMX is confusing or hard. Claude keeps a log of those moments in your project as you work; add to it too.

• A Windows 10 or 11 (64-bit) computer or a Mac. Installing Git may ask for an administrator's approval.
• The Claude desktop app, signed in with your club plan.
• A GitHub account, if you want to save your work online. You can add that later.

Open PowerShell from the Start menu and run these one at a time:

winget install --id Git.Git -e --source winget

irm bun.sh/install.ps1 | iex

If winget isn't recognized, install Git from git-scm.com instead.

Open Terminal and run git --version. If macOS offers to install developer tools, accept, wait for it to finish, and run it again. Then install Bun:

curl -fsSL https://bun.sh/install | bash

Close the window, open a new one, and run:

git --version
bun --version

You should see git version 2.… and 1.4.0 or higher. If either isn't found, open another new window: an install only reaches windows opened after it.

Use the folder where you keep your projects, such as projects in your home folder. If you don't have one yet, make it: mkdir $HOME\projects in PowerShell, or mkdir ~/projects in Terminal.

Keep projects out of Documents and Desktop, which OneDrive or iCloud often sync; syncing slows installs and can lock files while Claude is changing them.

Quit Claude completely (on Windows, right-click its icon near the clock and choose Quit; on a Mac, press Command-Q), then open it again so it can find Git and Bun. Open the Code tab and choose your projects folder.

Paste this as your first message:

I'm in the PathMX Builders Club. Read
https://pathmx.club/learn/start.guide.md and follow its "For Claude"
steps with me in this folder. Go one step at a time, tell me what each step
showed, and stop to ask me before anything that needs my sign-in.

Claude asks before running commands. Read what each one is for, and approve it if it makes sense. At the end, send Mark the report Claude writes.

Next time, open Claude in the project's own folder. Its instructions and the PathMX skill load from there.

You're helping a student builder set up PathMX and start a project from the PathMX builder starter. First read For agents working with a builder and follow it throughout; it covers working with the builder, logging PathMX feedback, and Windows notes.

Note every PathMX problem, confusion or guess from the start, including your own. They go in the project's pathmx-feedback.md once it exists (step B). If a step fails, stop, show the exact error, and check "If something goes wrong" below.

Run git --version and bun --version. Bun must be 1.4.0 or newer; if either is missing, ask the builder to finish step 1 and restart Claude.

Confirm the folder you have open is their projects folder, not Documents, Desktop or a synced folder. If it isn't, ask them where they keep projects.

Check git config --global user.name and git config --global user.email. If either is empty, ask the builder what to use (GitHub's noreply address keeps their email private) and set it. Note the OS version for the report (cmd /c ver on Windows, sw_vers -productVersion on a Mac).

Ask the builder what to call the project: a short name with dashes, such as trail-notes. Then, in the projects folder:

git clone https://github.com/pathmx/pathmx-builder-starter <name>
cd <name>
git remote remove origin
bun install --frozen-lockfile

Removing origin disconnects their copy from the starter; it's their project now. Set name in package.json to the project name.

This session started outside the project, so its instructions didn't load. Read the project's AGENTS.md and .claude/skills/pathmx-authoring/SKILL.md now and follow them. Add anything you noted in step A to pathmx-feedback.md.

Start the development server and keep it running in the background:

bun run dev

You should see a listen line whose url= ends in :3000/. Have the builder open http://localhost:3000 and confirm they see "Welcome to PathMX". If the computer asks whether Bun may accept network connections, they can decline; their own browser can still reach it.

Ask the builder what the site should be about; a sentence is enough. Then:

1. Rewrite paths/index.md with their title and a short introduction. Keep its first line, [@layout.default]: ./site.layout.md.
2. Add paths/about.md with a few lines of their own and a link back, [Home](./index.md), and link to it from the home page.
3. Run bun run check, which should report No issues found, then bun run pmx tree, which should list both pages.

Have them watch the open page update without reloading, then open /about.page.

git add -A
git commit -m "Make the starter my own"

Explain that a commit is a saved checkpoint they can return to. The starter's .gitignore already leaves out node_modules, db and .env.

Putting it on GitHub is optional. If they want to, they create an empty repository on github.com, choose private or public themselves, and give you its URL. Run git remote add origin <url> and git push -u origin main. The first push opens a GitHub sign-in window for them.

Skip this if the builder doesn't have a PathMX project yet. Otherwise clone it into the projects folder, read its AGENTS.md, and in it run:

bun install --frozen-lockfile
bun run check
bun run dev --port 3001

Keep the PathMX version it pins. Open the home page and one other page with the builder. Then offer to bring it into the club setup.

Make sure every problem from this session is in pathmx-feedback.md and committed. Then give the builder a short report to send Mark:

PathMX setup report
OS: …   Bun: …   PathMX Core: … (bun run pmx --version)
New project: name; whether install, dev, check and commit worked
Existing project: name, or skipped; whether install, check and dev worked
Feedback log: titles of the entries added, or none

Give exact error text. If something looks like a PathMX bug, say how to make it happen again. Remind them to open Claude in the project folder next time.

• git or bun isn't found: open a new terminal window. If Claude can't find them, quit Claude completely and open it again.
• Port 3000 is already in use: run bun run dev --port 3001 and open that port instead.
• Installs are very slow, or files are locked: move the project out of OneDrive or iCloud. Antivirus scanning can also slow the first install.
• PathMX itself fails (a command crashes, or a page won't render while check passes): log it, then send Mark the report with the exact error. On Windows, running PathMX in WSL, Linux inside Windows, is the fallback; we'll set that up together.

• Build out a site: Build a workshop site adds a shared layout, menu, styles and a reusable component.
• Put it online for someone else to open: start with How PathMX runs. That's the First deploy badge.
• Found a PathMX problem you can reproduce? Reporting it toward a fix earns Bug hunter.

All guides · Back to the Builders Club