Machine Setup

• Time required: 20–40 minutes 

• What this does: Installs Claude Code, Beads, Context7, subagent definitions, and the UI/UX Pro Max skill. 

• Where to do this: In your terminal (macOS Terminal, VS Code terminal, or WSL Ubuntu terminal).

• What you will have after this: Claude Code authenticated and configured with all plugins, MCP servers, skills, and your statusline.

Step 1: Install Claude Code

npm install -g @anthropic-ai/claude-code

Verify:

claude --version

Expected result: A version number like 1.x.x.

Now run the health check:

claude /doctor

This checks your installation. Fix any issues it reports before continuing.

Step 2: Authenticate Claude Code

claude

This opens Claude Code interactively. It will prompt you to authenticate:

1. It will open a browser window (or give you a URL to paste)

2. Sign in with your Anthropic account

3. Authorise Claude Code

4. Return to your terminal — you should see Claude Code's prompt (a > symbol)

Type /status to confirm you are connected. You should see your model and account info.

Type /exit to close Claude Code for now.

Step 3: Install Beads (bd)

Beads is our task tracker. Install it using Homebrew (macOS) or npm:

macOS (recommended):

brew install beads

Any platform:

npm install -g @beads/bd

Verify:

bd version

Expected result: A version number.

Step 4: Connect Beads to Claude Code

This installs hooks so Claude Code automatically loads and syncs with Beads at session start and before context compaction.

bd setup claude

Verify the setup:

bd setup claude --check

Expected result: All checks pass. You should see confirmation that SessionStart and PreCompact hooks are installed.

Step 5: Install Context7 MCP server

Context7 provides up-to-date library documentation to Claude. It is an MCP server — you add it using the claude mcp command.

Option A: Remote server (recommended — no local install needed):

claude mcp add --transport http --scope user context7 https://mcp.context7.com/mcp

Option B: Local server (if you prefer running it locally):

claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest

Verify: Open Claude Code and type:

/mcp

You should see context7 listed with a green/connected status.

Step 6: Install GitHub MCP server

GitHub's official MCP server gives Claude conversational access to GitHub's API during coding sessions. Instead of switching to the browser to read issues, check PR status, or read CI failure logs, Claude can do it directly.

This is separate from the gh CLI (which Claude can already use for basic operations) and the Claude Code GitHub Action (which runs in CI/CD). The MCP server provides richer, structured access that works naturally in conversation.

Prerequisites:

You should already have a GitHub Personal Access Token from Step 10 of Prerequisites. If not, create one now:

1. Go to  https://github.com/settings/tokens

2. Create a new token (classic) with these scopes: repo, read:org, workflow

3. Copy the token -- you will need it in the next step

Install the MCP server (user-level so it works across all projects):

claude mcp add --scope user --transport http github \ https://api.githubcopilot.com/mcp/ \ -H "Authorization: Bearer YOUR_GITHUB_PAT"

Replace YOUR\_GITHUB\_PAT with your actual token.

IMPORTANT: Do NOT put your PAT in any project file, .mcp.json, or committed config. The --scope user flag stores this in your personal Claude Code config only.

Verify: Open Claude Code and type /mcp. You should see github listed.

Test it by asking Claude: "List the open issues in \[your-repo-name\]"

Step 7: Check Serena MCP server

Serena provides Language Server Protocol (LSP) intelligence to Claude Code. Instead of Claude searching your codebase via grep and file reading (which burns context tokens), Serena gives Claude IDE-level semantic understanding: go-to-definition, find-all-references, type hierarchies, and symbol-aware navigation across 30+ languages including TypeScript, Python, Java, Go, Rust, and C#.

This is the same type of intelligence that Cursor and Windsurf get from their built-in IDE integrations. Without it, Claude Code's biggest disadvantage versus IDE-based agents is that it has to read entire files and guess at relationships between code entities.

Prerequisites: uv must be installed (Step 7 of Prerequisites).

Serena is installed per-project (not globally) because it needs to know which project to index. You will add it during Project Kickoff for each new project. But we verify the binary works now.

Verify uv can fetch Serena:

uvx --from git+https://github.com/oraios/serena serena --help

Expected result: Serena's help output prints. This confirms the binary downloads and runs. The actual per-project setup happens in Project Kickoff.

Step 8: Install VoltAgent subagent definitions

These are 100+ specialist subagent definitions (SQL, frontend, infra, QA, and more) that Claude Code can use as focused helpers.

Open Claude Code:

claude

Then type:

/plugin marketplace add VoltAgent/awesome-claude-code-subagents

When prompted about trust, review and approve.

Verify: Type:

/plugin list

You should see the VoltAgent subagents collection listed.

Type /exit to close Claude Code.

Step 9: Install obra/superpowers methodology plugin

Superpowers (40.9k GitHub stars, in the official Anthropic marketplace) provides a development methodology layer that auto-activates based on what Claude is doing. Your custom rules tell Claude WHAT conventions to follow. Superpowers tells Claude HOW to approach the work systematically.

Core skills that activate automatically:

• brainstorming: Forces requirement exploration before writing code

• write-plan / execute-plan: Implementation planning with batched execution

• test-driven-development: Auto-activates during feature implementation

• systematic-debugging: Auto-activates when debugging

• verification-before-completion: Activates before Claude claims work is done

These skills are token-light (~100 tokens of metadata at session start). Full skill content loads only when a skill activates.

Open Claude Code:

claude

Then type:

/plugin marketplace add obra/superpowers-marketplace /plugin install superpowers@superpowers-marketplace

When prompted about trust, review and approve.

Verify: Type:

/plugin list

You should see superpowers listed.

Type /exit to close Claude Code.

Step 10: Install Anthropic code-review plugin

The official Anthropic code-review plugin runs 5 parallel review agents on your PR branch, each analysing from a different angle: CLAUDE.md compliance, bug detection, git history context, previous PR comment review, and code comment verification. Each finding is scored 0-100 confidence. Only issues scoring 80+ are surfaced, which dramatically reduces false positives.

Open Claude Code:

claude

Then type:

/plugin install code-review@claude-plugin-directory

When prompted about trust, review and approve.

Verify: Type:

/help

You should see /code-review listed as an available command.

Type /exit to close Claude Code.

Step 11: Install Anthropic pr-review-toolkit plugin

The pr-review-toolkit provides 6 specialised review agents that activate based on your requests. Unlike code-review (which runs everything at once), these agents let you dig into specific concerns:

• comment-analyzer: Verifies documentation matches actual code

• pr-test-analyzer: Identifies test coverage gaps, prioritises by impact

• silent-failure-hunter: Detects swallowed errors and inadequate logging

• type-design-analyzer: Evaluates type invariants and encapsulation

• code-reviewer: Validates compliance with project guidelines

• code-simplifier: Suggests clarity improvements preserving functionality

These agents activate based on natural language. Ask "check if tests cover all edge cases" and the test analyser fires automatically.

Open Claude Code:

claude

Then type:

/plugin install pr-review-toolkit@claude-plugin-directory

When prompted about trust, review and approve.

Verify: Type:

/help

You should see /pr-review-toolkit:review-pr listed.

Type /exit to close Claude Code.

Step 12: Install UI/UX Pro Max skill & frontend-design (Anthropic official)

This skill gives Claude access to 50+ UI styles, 97 colour palettes, 57 font pairings, and 99+ UX guidelines.

Open Claude Code:

claude

Then type:

/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill

When prompted about trust, review and approve.

Then type:

/plugin marketplace add anthropics/claude-code

When prompted about trust, review and approve.

Then type:

/plugin install frontend-design@claude-code-plugins

When prompted about trust, review and approve.

Verify: Type:

/plugin list

You should see UI/UX Pro Max listed & frontend-design.

Type /exit to close Claude Code.

Step 13: Install Claude in Chrome (optional but recommended for UI work)

1. Open Google Chrome

2. Go to: https://chromewebstore.google.com/ and search for "Claude" by Anthropic

3. Click "Add to Chrome"

4. Click the puzzle piece icon (extensions) in Chrome's toolbar

5. Pin the Claude extension so it is always visible

6. Click the Claude extension icon and sign in with your Anthropic account

Important safety rules for Claude in Chrome:

• ONLY use it for verifying YOUR OWN local development servers (localhost)

• NEVER use it on banking, financial, or sensitive websites

• NEVER use it to enter passwords or personal information on third-party sites

• It has an ~11% prompt injection success rate on hostile pages — treat it as a developer tool, not a general browsing assistant

• It is NOT suitable for automated testing in CI/CD pipelines

• It only works on Chrome and Edge

Step 14: Install the Beads MCP server (optional — enables richer Beads integration)

uv tool install beads-mcp

Then add it to Claude Code:

claude mcp add --scope user beads-mcp -- beads-mcp

Verify: Open Claude Code, type /mcp, and confirm beads-mcp appears.

Step 15: Set your default model configuration

We use opusplan as our default — it uses Opus for planning/reasoning and Sonnet for code execution. This gives the best balance of intelligence and speed.

Open Claude Code:

claude

Type:

/model opusplan

To make this persist across sessions, set the environment variable. Add this to your shell profile:

macOS/Linux (add to ~/.zshrc or ~/.bashrc):

echo 'export ANTHROPIC_MODEL=opusplan' >> ~/.zshrc
source ~/.zshrc

Verify: Open a new Claude Code session and type /status. You should see opusplan as your model.

Step 16: Configure the statusline

The statusline shows your context usage, session cost, and current model at all times without needing to type /context or /cost. Since our workflow enforces a 60% context ceiling, having this visible at a glance prevents you from ever being surprised by context bloat.

In Claude Code type

/statusline show model name, context percentage with a colour-coded progress bar (green under 40%, yellow 40-60%, red above 60%), and session cost in AUD

Claude will generate a script and configure your settings automatically.

Verify: You should see a status bar at the bottom of your Claude Code session showing something like:

[Opus] ████░░░░░░ 38% context | $1.24

The bar turns yellow at 40% (time to start thinking about compacting) and red at 60% (you must compact or clear now).

This runs locally and consumes no API tokens.

Checkpoint: Before you continue

You should now have all of these installed:

• Claude Code (authenticated)

• Beads (bd) with Claude Code hooks

• Context7 MCP server

• VoltAgent subagent definitions

• UI/UX Pro Max skill

• Front end design

• Claude in Chrome (optional)

• Statusline configured with context and cost display

All good? Open Verify Your Setup and run the full verification.