Claude Code & GitHub CLI Setup

1 Step 1: Check the Prerequisites

Before you start, make sure you have:

• Git installed and configured, as in Step 1 of the Daily Git Terminal Workflow.
• A GitHub account in the Shattered-Vales-Studio organization, with two-factor authentication turned on.
• An SSH key added to GitHub (recommended). If you use more than one GitHub account, follow Managing Multiple GitHub SSH Keys first.
• A studio-provided Claude account. Use the account your lead provisions, not a personal one; see the data rules in LLM Prompting & AI Security.
• A terminal: Terminal or iTerm2 on macOS, your usual shell on Linux, and PowerShell or Git Bash on Windows.

2 Step 2: Install the GitHub CLI

The GitHub CLI lets you work with issues, pull requests, and repositories from the terminal. Claude Code uses it the same way you do, so installing it lets Claude work with GitHub too.

brew install gh

sudo apt install gh

winget install --id GitHub.cli -e --source winget

gh --version

3 Step 3: Authenticate the GitHub CLI

Run the login command and answer the prompts:

gh auth login

1. Where do you use GitHub? Choose GitHub.com.
2. Preferred protocol for Git operations? Choose SSH if you already have an SSH key on GitHub, otherwise HTTPS.
3. With SSH, it offers to upload a public key: select your existing key, or skip if it's already on GitHub. With HTTPS, answer Yes to "Authenticate Git with your GitHub credentials?" so git push works without passwords.
4. How would you like to authenticate? Choose Login with a web browser. Copy the one-time code shown, press Enter, paste the code in the browser, and approve.
5. If the browser asks you to authorize the Shattered-Vales-Studio organization, approve that too.

Confirm everything works:

gh auth status                                     # shows your account, protocol, and token scopes
gh repo list Shattered-Vales-Studio --limit 5      # should list studio repositories

Signed in to more than one GitHub account? gh auth switch changes the active account. Claude Code acts as whichever account gh is using.

4 Step 4: Install Claude Code

Install with the native installer for your platform. It keeps itself up to date automatically.

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

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

irm https://claude.ai/install.ps1 | iex

Piping a script from the internet into your shell is only safe from a source you trust. These are Anthropic's official installer URLs; don't use copies from anywhere else. Then check the installation:

claude --version
claude doctor          # checks the installation and reports problems

5 Step 5: Sign In to Claude Code

Open a terminal in any repository and start Claude Code:

cd ~/Source/<your-repo>
claude

1. On first launch, choose a theme, then choose the login method that matches your studio account: a Claude subscription account (Team or Enterprise), or an Anthropic Console account if your lead gave you API access.
2. A browser window opens. Sign in with your studio email and approve access. If the browser doesn't open, copy the URL from the terminal.
3. Back in the terminal, Claude Code asks whether you trust the files in this folder. Only say yes for repositories you know: Claude Code reads the project's configuration files, which could contain instructions.

Inside Claude Code, type /status to see which account and model you're using, /login to switch accounts, and /help for every command.

6 Step 6: Configure the Workspace

Claude Code starts every session knowing nothing about your project. Two kinds of files fix that: CLAUDE.md tells it how to work, and settings.json controls what it's allowed to do. Each exists at more than one level:

Create CLAUDE.md

If the repository doesn't have one, run /init inside Claude Code. It studies the codebase and drafts a CLAUDE.md. Review the draft carefully, then add the studio rules. Keep it short and specific; it's loaded into every session, so every line costs tokens. A typical studio CLAUDE.md:

# Claude Code Guidelines

## Context
- Read ARCHITECTURE.md before proposing changes or writing code.

## Issues
- Only work on GitHub issues labeled `agentic`: `gh issue list --label "agentic"`

## Git workflow
- Protected branches: `main`, `QA`, `Dev`. Never commit to them directly.
- Branch from Dev: `git checkout -b feature/issue-[number]-[short-description] Dev`
- Use Conventional Commits (feat, fix, docs, refactor, test, chore...).

## Pull requests
- Open PRs against Dev: `gh pr create --base Dev --title "..." --body "Resolves #[number]"`
- Never merge your own PR.

## Build and test
- Build: `...`
- Test: `...`  (run before every commit)

## When unsure
- If an issue is ambiguous, stop and ask instead of guessing.

Set permissions in .claude/settings.json

By default, Claude Code asks before editing files or running commands. Permission rules let you pre-approve safe, read-only commands (fewer interruptions), require confirmation for risky ones, and block access to secrets entirely. Rules in deny always win.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(gh issue list:*)",
      "Bash(gh issue view:*)",
      "Bash(gh pr view:*)",
      "Bash(gh pr diff:*)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(gh pr create:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./**/*.pem)",
      "Read(./**/*.key)"
    ]
  }
}

Type /permissions inside Claude Code to view and edit rules interactively. When it asks to run a command and you choose "don't ask again", the rule is saved to your local settings.

7 Step 7: Use Claude Code and gh Together

Describe what you want in plain language; Claude Code decides which commands to run and asks for permission when needed. Everything it does on GitHub is done as you, with your gh login, so you're accountable for it. A typical session for an issue:

# In the repository folder
claude

> List the open issues labeled agentic.
> Read issue #42 and outline a plan before changing anything.
> The plan looks good. Create the branch and implement it.
> Run the tests and show me the diff.
> Commit with a Conventional Commit message and open a PR into Dev.

8 Step 8: Troubleshoot Common Problems