Setting up Claude Code

by Mattias Wijkströmin AI, Setupon Posted on

Claude Code is Anthropic’s CLI-based AI coding assistant. I’ve been using it daily since 2026. It runs in the terminal, reads your files, runs commands, and edits code directly. Think of it as a colleague that lives in your shell.

This page covers installing, configuring, and migrating Claude Code on Windows.

Installation

Claude Code has several installation methods. The native installer is recommended — it doesn’t require Node.js and auto-updates in the background.

Native install (recommended):

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

This downloads and installs Claude Code as a standalone binary. No Node.js needed.

The installer may warn that %USERPROFILE%\.local\bin is not in your PATH. If claude --version doesn’t work after installing, add it:

# Add Claude Code to the user PATH (persists across sessions, no admin needed)
$binPath = "$env:USERPROFILE\.local\bin"
$currentPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
if ($currentPath -notlike "*$binPath*") {
    [System.Environment]::SetEnvironmentVariable('Path', "$currentPath;$binPath", 'User')
    Write-Host "Added $binPath to user PATH. Restart your terminal to pick it up."
} else {
    Write-Host "$binPath is already in PATH."
}

Alternative: WinGet:

winget install Anthropic.ClaudeCode

WinGet doesn’t auto-update — run winget upgrade Anthropic.ClaudeCode periodically.

Alternative: npm (if you already have Node.js):

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

Verify the installation:

claude --version

The native install auto-updates. For npm installs, upgrade with npm install -g @anthropic-ai/claude-code or claude update from within a session.

There’s also a standalone desktop app, a VS Code extension, and a web version that requires no installation at all.

API access

Claude Code talks to an API endpoint. You’ll need either a direct Anthropic API key, an AWS Bedrock setup, or — if your company runs a gateway — the gateway URL and auth token.

Configuration goes in %USERPROFILE%\.claude\settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-api-gateway/v1/passthrough",
    "ANTHROPIC_AUTH_TOKEN": "your-token-here"
  },
  "model": "opus",
  "theme": "dark"
}

For direct Anthropic API access, set ANTHROPIC_API_KEY instead and drop the ANTHROPIC_BASE_URL.

You can also override which models map to which tiers (Opus, Sonnet, Haiku) if your gateway uses custom model identifiers:

{
  "env": {
    "ANTHROPIC_SMALL_FAST_MODEL": "your-haiku-model-id",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "your-sonnet-model-id",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "your-opus-model-id"
  }
}

Windows Terminal profiles

I run Claude Code from dedicated Windows Terminal profiles — separate from my regular PowerShell profile, each pointing to a specific working directory. This keeps Claude sessions visually distinct and lets me open them with one click.

To add a Claude profile: open Windows Terminal settings → Add a new profile → Duplicate an existing one, then set:

  • Name: something like “Claude” or “Claude (my-project)”
  • Command line: %ProgramFiles%\PowerShell\7\pwsh.exe (or wherever your PowerShell Core lives)
  • Starting directory: the repo or workspace root you want Claude to start in
  • Font face: CaskaydiaCove NF (or any Nerd Font — Claude Code’s status line uses special characters)
  • Icon: optionally set a custom icon to tell profiles apart at a glance

Having the starting directory pre-set matters because Claude Code’s project context — memories, sessions, settings — is keyed to the directory you launch from.

What Claude Code stores and where

All of Claude Code’s state lives under two locations:

Global config — %USERPROFILE%\.claude\

Path What it is
settings.json API tokens, model preferences, theme, global permissions allowlist
CLAUDE.md Global instructions loaded every session — your persistent prompt
commands\ Custom slash commands (.md files — invoked with /command-name)
memory\ Global memories (MEMORY.md index + individual .md files)
projects\<path-encoded>\memory\ Project-specific memories
projects\<path-encoded>\*.jsonl Session transcripts (browsable via /resume)

The projects\ subfolder uses an encoded form of your repo path as the folder name. The encoding: replace :\ with --, then every remaining \ with -. So F:\dev\my-app becomes F--dev-my-app. This is how Claude Code connects a directory to its sessions and memories.

Everything else under .claude\ — sessions\, cache\, daemon\, file-history\, etc. — is ephemeral runtime state that gets recreated automatically.

Project-level config — inside each repo

Path What it is
.claude\settings.json Shared project settings (committed to git)
.claude\settings.local.json Local project permissions (gitignored)
.claude\commands\ Project-specific custom commands
CLAUDE.md Project instructions

These travel with the repo. The only exception is settings.local.json, which is gitignored — you’ll need to transfer that manually if it exists.

Configuring Claude Code

CLAUDE.md — your persistent prompt

CLAUDE.md is the most powerful configuration file. It’s loaded into context at the start of every session and acts as standing instructions. You can have one at the global level (%USERPROFILE%\.claude\CLAUDE.md) and one per repo (in the repo root).

Use it for things like:

  • Code style rules (“use public class, not internal“, “sort usings”, “add arrange/act/assert comments in tests”)
  • Workflow conventions (“use draft PRs”, “branch names follow teams/<team>/<jira-id>-<desc>“)
  • Project-specific knowledge (“the EntityTypeProvider silently excludes internal types”)
  • Memory system instructions (“read the memory index at startup”)

Memories

Claude Code has a file-based memory system. When you tell it to “remember this”, it writes a markdown file under memory\ with frontmatter (name, description, type) and links to related memories. It loads relevant memories at the start of each session based on the index in MEMORY.md.

Memory types:

  • user — who you are (role, preferences)
  • feedback — corrections and confirmed approaches (“don’t use var“, “chain commands with separate tool calls, not &&“)
  • project — ongoing work, goals, constraints
  • reference — pointers to external resources (Jira, Confluence, API tokens)

Memories accumulate over time and make Claude Code progressively better at working the way you work. They’re the main reason migrating .claude\ matters.

Custom commands

Custom commands are markdown files in commands\ that define reusable prompts. Invoke them with /command-name during a session.

I use commands for things like:

  • /fix-issue — takes a Jira issue ID, fetches details, creates a branch, implements the fix
  • /cherry-pick — cherry-picks a merged PR to a release branch
  • /retro-summary — generates a retrospective summary from recent Jira activity
  • /push-command and /pull-command — sync commands to/from a shared Confluence page

Commands can be global (%USERPROFILE%\.claude\commands\) or project-specific (.claude\commands\ in the repo).

Permissions

The permissions.allow array in settings.json controls which commands Claude Code can run without asking each time:

{
  "permissions": {
    "allow": [
      "PowerShell(git *)",
      "PowerShell(gh *)",
      "PowerShell(dotnet *)",
      "Bash(git *)",
      "Bash(curl *)"
    ]
  }
}

Start conservative and add entries as you find yourself approving the same prompts repeatedly. There’s also a project-level settings.json (committed, shared with the team) and settings.local.json (local, gitignored) for per-repo permissions.

Migrating to a new machine

When you move to a new computer, you want to bring along your config, memories, custom commands, and optionally your session history. Here’s the approach.

Archive on the old machine

$rar = "C:\Program Files\WinRAR\rar.exe"
$staging = "$env:USERPROFILE\Desktop\migration"
New-Item -ItemType Directory -Force $staging

# Archive the entire .claude directory
& $rar a -r -ep1 "$staging\dot-claude.rar" "$env:USERPROFILE\.claude\*"

# Also grab the state file (sits in %USERPROFILE% directly, not inside .claude).
# Contains onboarding state, feature flags, and project trust — avoids
# first-launch setup prompts on the new machine.
Copy-Item "$env:USERPROFILE\.claude.json" "$staging\.claude.json"

If you also want to clean up git worktrees first (Claude Code creates them under <repo>\.claude\worktrees\ and they can be large):

cd <repo>
git worktree list
git worktree remove <name>  # for any you don't need

Set up the new machine

  1. Install Claude Code (see Installation above)
  2. Extract the archive:
$rar = "C:\Program Files\WinRAR\rar.exe"

# This is where the transferred files were placed
$transfer = "$env:USERPROFILE\Desktop\transfer"

& $rar x "$transfer\dot-claude.rar" "$env:USERPROFILE\.claude\"

Copy-Item "$transfer\.claude.json" "$env:USERPROFILE\.claude.json"
  1. Review settings.json — update any API tokens that are machine-specific or expired

Preserving old sessions and project memories

If your repos end up at a different path on the new machine (say, C:\dev\repos → D:\work\repos), Claude Code won’t find old sessions or project memories because it looks in a folder named after the new path.

Option A — junctions: Create NTFS junctions from the old paths to the new locations. Lightweight, transparent, everything works.

New-Item -ItemType Directory -Force "C:\dev"
New-Item -ItemType Junction -Path "C:\dev\repos" -Target "D:\work\repos"

Option B — rename project folders: Rename the encoded folders under %USERPROFILE%\.claude\projects\ to match the new paths. No phantom directories, but you need to apply the encoding rule manually.

$projects = "$env:USERPROFILE\.claude\projects"
# Old: C--dev-repos-my-app → New: D--work-repos-my-app
Rename-Item "$projects\C--dev-repos-my-app" "D--work-repos-my-app"

You can optionally prefix old session titles with [MIGRATED] and rewrite hardcoded file paths inside the .jsonl transcripts. See the full migration guide for the detailed scripts.

If your repos land at the same path on both machines, none of this is needed — everything just works.

Verify

cd <your-repo>
claude

Check that:

  • Memories load (if you reference them in your CLAUDE.md)
  • Custom commands appear (type / and look for them)
  • Model preference is preserved
  • /resume shows old sessions (if you migrated them)

Tips

Start with CLAUDE.md. Even a few lines of project conventions saves time on every session. It compounds.

Let memories build naturally. Don’t try to front-load them. When Claude does something wrong, say “remember: always do X instead” — it creates a memory and won’t repeat the mistake.

Use custom commands for repetitive workflows. Anything you do more than twice is a candidate. Commands can include $ARGUMENTS placeholders for dynamic input.

Keep the terminal profile starting directory set to your repo root. Claude Code’s project context depends on it.

Upgrade regularly. Claude Code ships updates frequently — new features, better tool use, faster performance. The native install auto-updates; for other methods, run claude update from within a session.

Leave a Comment

Your email address will not be published. Required fields are marked *