From scratch

This page is for the person who has never done any of this: a laptop, a work email, and a report to publish. It takes about half an hour, once. After it, everything else is a conversation with Claude Code inside the project (/setup-project, /new-report, /publish) — you will not need to remember these tools.

What you end up with

A GitHub account that belongs to the organisation · Git, Node and the GitHub command line on your computer, signed in · Claude Code, signed in · VS Code (optional, recommended) · the project folder on your machine, ready for claude.

1. A GitHub account, in the organisation

1. Create an account at github.com/signup with your work email. Choose a username you are happy to see next to reports (it appears in the history of every change).
2. Turn on two-factor authentication when GitHub asks (Settings → Password and authentication). The organisation requires it.
3. Send your username to whoever looks after the organisation and ask to be added to the organisation (for CSDR: SustainableDevelopmentReform). They add you under People → Invite member.
4. Accept the invitation — it arrives by email and also at https://github.com/orgs/<organisation>/invitation. Until you accept, you can see nothing.

That is all GitHub asks of you. You will never type into GitHub’s website again if you don’t want to; the command line and Claude Code do the rest.

2. The tools

Pick your system. Everything below is free.

macOS

Open Terminal (⌘ Space, type “Terminal”) and paste one line at a time:

xcode-select --install                                  # Git and Apple's build tools (a dialog appears; click Install)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"   # Homebrew, the package manager
brew install gh node@22 fnm                             # GitHub CLI · Node 22 · a Node version switcher
corepack enable                                         # turns on pnpm, the package tool this project uses
brew install --cask visual-studio-code                  # optional: VS Code

If Homebrew ends with a note about adding it to your PATH, paste those two lines it prints, then close and reopen Terminal.

Windows

Open PowerShell (Start, type “PowerShell”) and paste one line at a time:

winget install --id Git.Git -e
winget install --id GitHub.cli -e
winget install --id OpenJS.NodeJS.LTS -e                # Node 22 LTS
winget install --id Microsoft.VisualStudioCode -e       # optional: VS Code

Close PowerShell and open it again so the new commands are found, then corepack enable. Where this guide says “terminal”, use PowerShell (or Git Bash, which Git installed).

Check

git --version      # git version 2.x
node -v            # v22.13 or newer (the project needs ≥ 22.13)
pnpm -v            # 10.x
gh --version       # gh version 2.x

Anything missing → close the terminal, open it again, try once more; then ask.

3. Sign the GitHub command line in

gh auth login

Answer: GitHub.com → HTTPS → Authenticate Git with your GitHub credentials? Yes → Login with a web browser. Copy the one-time code it shows, press Enter, paste the code in the browser, approve. Back in the terminal:

gh auth status     # Logged in to github.com account <you>

This is the sign-in Claude Code uses to create repositories, open pull requests and merge for you. Nothing else needs a password.

4. Claude Code

npm install -g @anthropic-ai/claude-code    # macOS · Windows PowerShell alike
claude                                       # first run: choose "Log in", your browser opens, sign in to your Claude account

(Alternative installers: macOS curl -fsSL https://claude.ai/install.sh | bash, Windows irm https://claude.ai/install.ps1 | iex.) You need a Claude account with Claude Code access (a Pro/Max/Team plan, or an organisation API key your admin gives you). Type /exit to leave. If you use VS Code, install the Claude Code extension from the Extensions view too — it runs the same thing in a side panel.

5. The project on your computer

Either start a new project from the template:

gh repo create <organisation>/<project-name> --template SustainableDevelopmentReform/csdr-project --private --clone
cd <project-name>

(--private matters: the organisation’s deployment keys reach private repositories only. Creating the repository also runs a first deploy by itself — green, and it publishes nothing: the two addresses are reserved and show a being set up page until /setup-project below has been merged.)

or join an existing one:

gh repo clone <organisation>/<repo-name>
cd <repo-name>

Then:

pnpm install       # once; a minute or two
claude             # you are now talking to the project

For a new project say /setup-project — Claude asks what the site is called, where it should live, who may see the private site and how they sign in, then opens the first pull request; merging it publishes both sites. For an existing project just start: /new-report, /validate, /publish, /update-template. Claude runs every git command; you never type git.

If you use VS Code

code . inside the project folder opens it; the terminal is at View → Terminal (⌃). Run claude` there, or use the Claude Code panel. Everything else is the same.

When something goes wrong

• gh: command not found / claude: command not found — the terminal was open before you installed it. Close it, open a new one.
• “Permission denied” or “not found” when creating or cloning a repository — your organisation invitation is not accepted yet (step 1.4), or gh auth status says you are not logged in (step 3).
• node -v shows 18 or 20 — an older Node came first. macOS: fnm install 22 && fnm use 22 (and follow fnm’s one-line shell setup); Windows: uninstall the old Node from Settings → Apps and rerun the winget line.
• Corporate laptop blocks installers — ask IT to install Git, Node 22, GitHub CLI and VS Code; the rest (steps 3–5) needs no admin rights.
• You do not have a Cloudflare login — correct: you never need one. Publishing runs in GitHub Actions with the organisation’s credentials; see Deploy.