Skip to content

Getting started — new developer setup

Welcome to the mcc-systems codebase. This guide gets you from zero to making your first change. Follow it step by step — don't skip ahead.

Important: Throughout this guide, when you see terminal commands, enter them one at a time. Type (or paste) one command, press Enter, wait for it to finish, then move to the next. Don't paste multiple commands at once.

What you're working with

The mcc-systems monorepo contains two apps: the BMS (Business Management System) and the Client Portal. Both are React + TypeScript apps backed by Supabase, deployed on Vercel. You'll use VS Code as your editor and Claude Code (CC) as your AI coding assistant — it lives inside VS Code and can read, write, and run code.

Claude Code is a developer tool. You open the project in VS Code, tell CC what to build, review the changes it proposes, and approve them. It reads the entire codebase, understands the project structure, follows the project conventions automatically, runs the build to catch errors, and commits to GitHub — all from inside VS Code.

Step 1: Install VS Code

Download from https://code.visualstudio.com/ and install it. It's free.

Step 2: Install Claude Code

Open Terminal and run:

curl -fsSL https://claude.ai/install.sh | bash

After it installs, run:

claude --version

You should see a version number. If you do, it's working.

Now run:

claude

It will open your browser and ask you to sign in. Sign in with the company Claude account (subscriptions@matthewscleaningco.com.au).

Step 3: Install the Claude Code VS Code extension

  1. Open VS Code
  2. Press Cmd+Shift+X to open Extensions
  3. Search for "Claude Code"
  4. Install the one published by Anthropic (it has millions of installs)

You'll see a spark icon (✱) in the sidebar — that's Claude Code. The extension gives you a chat panel inside VS Code with inline diffs showing proposed changes and accept/reject buttons.

Step 4: Install Git (if not already installed)

Open Terminal and run:

git --version

If Git is already installed, you'll see a version number — move on to Step 5.

If not, macOS will pop up a dialog offering to install Xcode Command Line Tools. Click Install and wait for it to finish (a few minutes). Then run git --version again to confirm.

Step 5: Authenticate with GitHub

The repo is private, so you need to authenticate with GitHub before you can clone it. First, check your email for Glenn's GitHub invitation and accept it.

Now install the GitHub CLI:

brew install gh

Then log in:

gh auth login

It will ask you a series of questions. Choose: - GitHub.com - HTTPS - Yes (authenticate Git with GitHub credentials) - Login with a web browser

It will give you a one-time code, open your browser, and ask you to paste the code. Do that, then authorise the app. Once Terminal says "Logged in", you're done.

Step 6: Clone the repo

cd ~

git clone https://github.com/glenn-mcc/mcc-systems.git

cd mcc-systems

Now open the project in VS Code:

code .

If the code command doesn't work, open VS Code manually, then press Cmd+Shift+P, type "Shell Command: Install 'code' command in PATH", and hit Enter. Then try code . again.

Step 7: Install Node.js and project dependencies

Open Terminal and run:

node --version

If you get a version number (18 or higher), skip to the npm ci step below. If not, install Node.js:

  1. Go to https://nodejs.org/
  2. Download the LTS version
  3. Run the installer
  4. Close and reopen Terminal, then run node --version to confirm

Now install the project dependencies. Install them for the app you'll be working in — ask Glenn which one applies to you:

cd ~/mcc-systems/apps/bms
npm ci

or

cd ~/mcc-systems/apps/client-portal
npm ci

This downloads all the libraries the app needs. It takes a minute or two the first time.

Step 8: Supabase MCP

The repo includes a .mcp.json file that connects Claude Code to our Supabase dev database. This lets CC query tables, create migrations, and manage the database — all from within VS Code.

You don't need to configure anything. The first time CC tries to use a Supabase tool, it will open your browser and ask you to log in to Supabase. Glenn needs to invite you to the Supabase organisation first — check with him before this step. Log in when prompted and grant access.

The MCP connection is locked to the dev database only. This is intentional — MCP should never talk to production.

Step 9: Configure Git identity

cd ~/mcc-systems

git config user.name "Your Name"

git config user.email "you@matthewscleaningco.com.au"

Step 10: Verify everything works

Open the Claude Code panel in VS Code (click the ✱ icon in the sidebar) and ask CC:

What files are in the repo root?

CC should list the repo contents. If it does, you're connected and ready.

Now try a build. Ask CC:

Please run npm run build from the app directory and tell me the result.

If the build succeeds, you're fully set up.

When to use Claude.ai instead of Claude Code

Claude Code is great at executing well-defined tasks: build this component, add this route, fix this error. But for bigger-picture thinking, use Claude.ai in the browser. Specifically:

  • Planning a new feature — before telling CC to build something complex, talk it through with Claude.ai first. Describe what you want, what data it needs, how it should look. Claude.ai will help you think through the design and write step-by-step instructions for CC.
  • Tricky problems CC is struggling with — if CC keeps going in circles on a bug, copy the error and relevant context into a Claude.ai thread. It can analyse the problem with fresh eyes and give you instructions to relay back to CC.
  • Architecture decisions — if you're unsure how to structure something or whether an approach fits within your allowed boundaries, ask Claude.ai.
  • Writing specs — for non-trivial features, Claude.ai can help you write a spec before you start building. See docs/admin/spec-and-plan-guide.md.

Think of it this way: Claude.ai is the architect, CC is the builder. You can go straight to CC for simple tasks, but for anything that needs planning or problem-solving, start with Claude.ai.

General tips

  • Start small. Your first task should be something simple. Get the full cycle working (code → build → commit → push) before attempting anything complex.
  • CC reads CLAUDE.md automatically. This file contains all the project conventions. You don't need to memorise them — CC follows them.
  • If CC suggests modifying a file outside your area, that's a red flag. Push back and ask it to find a way within your allowed scope.
  • If you want to build something non-trivial, write a quick spec first. See docs/admin/spec-and-plan-guide.md. This saves time by forcing you to think through the design before CC starts coding.
  • If you get stuck, ask Glenn.

What happens after you push

Pushing to GitHub does not automatically deploy to production. Nothing goes live until Glenn runs the production deployment manually. When your changes are ready, let Glenn know and he'll deploy.

For the full picture of how environments work and why, see Development environment & database change management.

Quick reference

What Where
Project conventions CLAUDE.md (repo root)
BMS app apps/bms/
Client Portal app apps/client-portal/
Spec guide docs/admin/spec-and-plan-guide.md
BMS URL (prod) bms.matthewscleaningco.com.au
Portal URL (prod) portal2.matthewscleaningco.com.au