--- title: Start a PathMX project description: Set up a Windows or Mac computer for PathMX, then have Claude start a project from the builder starter and work through it with you. --- # 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. --- ## What you need - A Windows 10 or 11 (64-bit) computer or a Mac. Installing Git may ask for an administrator's approval. - The [Claude desktop app](https://claude.ai/download), signed in with your club plan. - A GitHub account, if you want to save your work online. You can add that later. --- ## 1. Install Git and Bun ### On Windows Open PowerShell from the Start menu and run these one at a time: ```powershell winget install --id Git.Git -e --source winget ``` ```powershell irm bun.sh/install.ps1 | iex ``` If `winget` isn't recognized, install Git from [git-scm.com](https://git-scm.com/download/win) instead. ### On a Mac 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: ```sh curl -fsSL https://bun.sh/install | bash ``` ### Check both Close the window, open a new one, and run: ```sh 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. --- ## 2. Open Claude in your projects folder 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. --- ## 3. Hand it to Claude Paste this as your first message: ```text 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. --- ## For Claude 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](./agents.guide.md) 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. --- ### A. Check the computer 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). --- ### B. Start a project from the starter Ask the builder what to call the project: a short name with dashes, such as `trail-notes`. Then, in the projects folder: ```sh git clone https://github.com/pathmx/pathmx-builder-starter cd 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: ```sh bun run dev ``` You should see a `listen` line whose `url=` ends in `:3000/`. Have the builder open 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. --- ### C. Make it theirs 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`. --- ### D. Save it with Git ```sh 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 ` and `git push -u origin main`. The first push opens a GitHub sign-in window for them. --- ### E. Open an existing project 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: ```sh 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](./agents.guide.md#existing-project). --- ### F. Write the setup report Make sure every problem from this session is in `pathmx-feedback.md` and committed. Then give the builder a short report to send Mark: ```text 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. --- ## If something goes wrong - **`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. --- ## Next - Build out a site: [Build a workshop site](https://docs.pathmx.dev/docs/start/build-a-site.guide) adds a shared layout, menu, styles and a reusable component. - Put it online for someone else to open: start with [How PathMX runs](https://docs.pathmx.dev/docs/start/runs.guide). That's the [First deploy](../badges/first-deploy.badge.md) badge. - Found a PathMX problem you can reproduce? Reporting it toward a fix earns [Bug hunter](../badges/bug-hunter.badge.md). [All guides](./index.md) · [Back to the Builders Club](../index.md)