Setup guide

From zero to a working workspace.

This guide takes you from no installed tools to a live Claude Code session inside your project repo. Budget 45–60 minutes the first time through. Work through it in order — later steps assume earlier ones worked.

Before you start

You'll need three things ready:

  • A computer you can install software on (laptop or desktop). Mac, Windows (with WSL), or Linux all work. Chromebooks need GitHub Codespaces — ask us.
  • A GitHub account using the email you applied with.
  • A Claude account (claude.ai). The program covers a Claude Code plan — we'll send credentials after matching.
Not matched yet? You can still read this guide to get a feel for what the program's tooling looks like. The actual installation steps need your pair repo, which we create on match day.

1 · Install Claude Code

Claude Code is the terminal-based AI pair-programmer that anchors the Orchid workflow. It lives in your project repo and reads CLAUDE.md at session start to calibrate to you.

On macOS or Linux

Open a terminal and run:

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

Then authenticate:

claude login

Follow the browser prompt. When it returns you to the terminal, you're in.

On Windows (WSL)

Claude Code runs inside the Windows Subsystem for Linux. If you don't have WSL yet:

wsl --install

Restart, open Ubuntu from the Start menu, then run the macOS/Linux steps above from inside the Ubuntu terminal.

Verify the install

claude --version

You should see a version number. If not, jump to Troubleshooting.

2 · GitHub setup

You need the GitHub CLI (gh) to work with your pair repo without fighting HTTPS tokens. Install it and authenticate:

macOS

brew install gh
gh auth login

Linux / WSL

sudo apt update
sudo apt install gh
gh auth login

When gh auth login prompts you, pick GitHub.com → HTTPS → Login with a web browser. Paste the one-time code it gives you into the browser window.

One-time git identity. If git asks for your name/email on your first commit, set them: 
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

3 · Clone your pair repo

When you're matched, Orchid creates a private repo for your pair from the intern template. It'll be named something like pair-jdoe-acme-2026. You'll get an email invite and the repo URL.

Pick a folder to work in — we suggest ~/OrchidWork — then clone:

mkdir -p ~/OrchidWork
cd ~/OrchidWork
gh repo clone orchid-initiative/pair-jdoe-acme-2026
cd pair-jdoe-acme-2026

The repo comes pre-loaded with:

  • CLAUDE.md — your session guardrails, already filled in with your project and communication preferences.
  • 02-Work/problem-brief.md — the locked scope from your host.
  • .github/pull_request_template.md — the PR structure we expect.
  • Pre-configured .gitignore, pre-commit hooks, and a README.md with project-specific notes.

4 · Your first Claude Code session

From inside the repo:

claude

That's it. Claude Code will read CLAUDE.md automatically and address you by name.

Your first session has one goal: understand the Problem Brief. Try this opener:

Say to Claude: "Let's start by reading the Problem Brief together. Walk me through it section by section, flag anything that seems ambiguous, and list the three questions I should bring to my first sync with my host."

Don't write code yet. Don't ask for a plan yet. The first session is about loading context, identifying unknowns, and drafting smart questions. Your end-of-day journal should capture what you learned and what's still unclear.

5 · Obsidian vault

Obsidian is a free note-taking app we use for journaling and long-form writing. Your pair repo includes a starter vault at vault/ — open it in Obsidian once:

  1. Download and install Obsidian from obsidian.md.
  2. On first launch, click Open folder as vault.
  3. Point it at ~/OrchidWork/pair-jdoe-acme-2026/vault/.

The vault is organized into 01-Journal, 02-Work, 03-Comms, and so on — see CLAUDE.md for the full layout. The journal folder is private; it stays out of the shared repo. The other folders sync via git like the rest of the codebase.

6 · Verify everything works

Run through this checklist before your first 1:1 with your host:

  • claude --version returns a version number.
  • gh auth status shows you're logged in.
  • You can cd into your pair repo and run git status cleanly.
  • Obsidian opens your vault folder without errors.
  • You've made one trivial commit — for example, adding your name to README.md — pushed to a feature branch, and opened a PR. Self-review it, then merge it.
  • Today's journal entry exists at vault/01-Journal/YYYY-MM-DD.md with at least three lines of reflection on the Problem Brief.

If all six check, you're set. If any of them don't, read on.

Linux tips (if this is new for you)

You don't need to become a Linux expert for this program, but a handful of commands will carry you through the summer. Claude Code can explain any of these — ask it.

  • pwd — where am I right now?
  • ls — what's in this folder?
  • cd foldername — move into a folder. cd .. moves up one.
  • cat file.md — print a file to the terminal.
  • mkdir newfolder — create a folder.
  • mv old new / cp src dst / rm file — move, copy, delete. Be careful with rm; it doesn't go to a trash can.
Rule of thumb. If a terminal command would delete, overwrite, or reach outside your current folder, ask Claude to explain what it does before running it. This is in the CLAUDE.md for a reason.

Troubleshooting

claude: command not found

The install script finished but your shell doesn't see the binary. Run source ~/.bashrc (or ~/.zshrc on recent macOS) to reload your shell, then try again. Still stuck? Close the terminal completely and open a fresh one.

gh auth login won't open a browser

Happens most often on WSL. Pick the Login with a token option instead, then follow the link it prints to create a Personal Access Token with the scopes it lists.

Claude Code won't start — authentication errors

Run claude logout then claude login again. Make sure you're signed into the account that matches the email we sent your credentials to.

Git pre-commit hooks block my commit

This is intentional — the hook caught something (usually a secret pattern, a giant file, or a formatting issue). Read the hook's output, fix the cause, stage again, and re-commit. Never bypass with --no-verify without explicitly asking your host first.

Obsidian can't find my vault

You pointed it at the repo root instead of the vault/ subfolder. Close it, reopen, and choose Open folder as vault pointed at the subfolder.

Getting help

Stuck past the 30-minute mark? Run through the stuck protocol first — it's in your CLAUDE.md:

  1. Have I asked Claude, clearly and specifically?
  2. Have I tried something concrete and documented what happened?
  3. Do I have a specific question — not "it doesn't work" but what I expected vs. what I got?

If all three pass and you're still stuck, post in the cohort Discord (invite goes out on match day) or email help@orchid-initiative.com. For anything that blocks project work for more than a day, ping your host directly.

This guide is living. If something was unclear, outdated, or wrong when you worked through it — tell us, or edit it and send a PR. The next cohort will thank you.