User environment — global Claude Code settings¶

The user-level Claude Code configuration lives entirely under ~/.claude/ on your local machine. It applies to every repo you open. Nothing in this directory is ever committed to any repo.

Full directory structure¶

C:\Users\KristopherTurner\.claude\
├── CLAUDE.md                        ← developer identity and universal conventions
├── settings.json                    ← permissions, env vars, hooks, status line config
├── statusline.ps1                   ← custom terminal status bar script
├── config.json                      ← API key config (managed by Claude Code)
├── agents/
│   ├── triage-lookup.md
│   ├── markdown-prose-editor.md
│   ├── azurelocal-domain-expert.md
│   ├── mkdocs-material-doctor.md
│   ├── turner-module-scaffold-engineer.md
│   ├── mms-2026-demo-presenter.md
│   └── _archive_2026-04-30/         ← retired agents (do not delete — audit trail)
│       ├── azure-local-researcher.md
│       ├── docs-writer.md
│       └── quick-lookup.md
└── hooks/
    └── check-context.ps1            ← UserPromptSubmit hook; triggers memory dump at 90k tokens

CLAUDE.md — what belongs here¶

The ~/.claude/CLAUDE.md is your developer identity file. It should contain everything true about you and your environment regardless of which repo you are in:

Your name, email, role, and professional context
Preferred language and tooling defaults (PowerShell 7, az CLI, gh CLI)
Azure environment (ADO org, Key Vault name)
Universal coding conventions (naming, commit format, output patterns)
The platform repo path on this machine
Global Claude Code autonomous/confirm defaults

Does not belong here: anything repo-specific, any secret values, any credentials.

Recommended CLAUDE.md content¶

# Developer environment — Claude Code global context

## Who I am

Kristopher Turner
kris@hybridsolutions.cloud
Senior Product Technology Architect, TierPoint | Microsoft MVP (Azure) | MCT
Owner, Hybrid Cloud Solutions LLC — hybridsolutions.cloud
Blog — thisismydemo.cloud | Country Cloud Boy

## Primary platform and tooling

- All scripts: PowerShell 7+ only. Never PS 5.1. Never Bash.
- Source control: git, with ADO as primary remote and GitHub for open source
- Azure CLI (az): authenticated as kris@hybridsolutions.cloud
- GitHub CLI (gh): authenticated via hcs-github-org-pat from kv-hcs-vault-01
- Editor: VS Code

## Azure environment

- ADO org: https://dev.azure.com/hybridcloudsolutions
- Key Vault: kv-hcs-vault-01
- Subscription ID: be069ae1-fc96-4a07-9f8e-5994d83a817d
- Azure login: kris@hybridsolutions.cloud
- Platform Engineering repo: E:\git\platform

## Universal coding conventions

- PowerShell: #Requires -Version 7.0, Set-StrictMode -Version Latest, $ErrorActionPreference = 'Stop'
- Parameters: $PascalCase. Local variables: $camelCase.
- Approved PS verbs only. Verb-Noun naming for all functions.
- All docs: Markdown only. No Word docs.
- Diagrams: draw.io only. Commit .drawio XML alongside .png.
- Commit format: type(scope): short description
- Never commit secrets, tokens, or connection strings.
- ADO work items: AB#<id> in commits.

## Documentation sites

- MkDocs with mkdocs-material theme
- Reference: azurelocal-ranger (org: azure-local-cloud)

## Claude Code behavior — global defaults

**Run autonomously:**
- Read, search, grep any file
- Write and edit files
- Run PowerShell scripts already in the repo
- az CLI read operations
- git add, git commit, git push
- mkdocs build and serve

**Always confirm before:**
- Creating or deleting Azure resources
- Any az CLI write operation
- Running destructive operations
- Making API calls to external services
- Installing software

## Subagents available (user-level — every repo)

| Agent | Model | Purpose |
|---|---|---|
| triage-lookup | haiku | Fast read-only: "what does this file say", find references, summarize logs |
| markdown-prose-editor | sonnet | Markdown/MDX editing — runbooks, READMEs, ADRs, blog drafts |
| azurelocal-domain-expert | opus | Deep cross-repo research: Azure Local, Hyper-V, S2D, Network ATC |
| mkdocs-material-doctor | sonnet | MkDocs Material theme, plugins, nav, mike versioning |
| turner-module-scaffold-engineer | sonnet | Turner Legacy scaffold modules (board, budget, calendar, finance, travel) |
| mms-2026-demo-presenter | sonnet | MMS 2026 session demos |

settings.json — structure and key fields¶

The user-level settings.json controls behavior for every session.

Required fields¶

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "pwsh.exe -NoProfile -ExecutionPolicy Bypass -File \"C:/Users/KristopherTurner/.claude/hooks/check-context.ps1\"",
            "timeout": 30
          }
        ]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "pwsh -NoProfile -File C:/Users/KristopherTurner/.claude/statusline.ps1"
  },
  "effortLevel": "high",
  "verbose": true,
  "model": "opusplan"
}

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is required for multi-agent parallelism. Without it, agent teams cannot run in parallel.

permissions.allow¶

The permissions.allow array accumulates pre-approved tool call patterns over time. When Claude Code prompts for permission and you approve, the approved pattern can be added here to avoid future prompts.

Common pattern forms: - "Bash(git add:*)" — matches git add with any arguments - "Bash(git commit -m ':*)" — matches commit messages starting with any string - "Bash(pwsh -NoProfile -Command ':*)" — matches any PowerShell -Command invocation - "Read(//e/git/**)" — pre-approves reading all files under E:\git\ - "WebFetch(domain:github.com)" — pre-approves fetching from github.com

See templates/claude/settings.json.template for a clean starting point for repo-level settings.

User-level agents¶

All six user-level agents live in ~/.claude/agents/. They are available in every repo session automatically. See agents for the full format specification and the complete roster.

Context-watch hook¶

~/.claude/hooks/check-context.ps1 fires on every user prompt. It calculates the current session context token count from the transcript and injects a [CONTEXT-WATCH] system reminder when the total exceeds 90,000 tokens.

The reminder instructs Claude Code to write a memory dump before responding, so work-in-progress state survives a /clear. The user always handles the actual /clear — the hook never blocks or clears automatically.

The hook source is maintained at scripts/hooks/check-context.ps1 in this platform repo. Keep the two copies in sync.

Status line¶

~/.claude/statusline.ps1 provides the Claude Code terminal status bar. It reads JSON from stdin (provided by the Claude Code harness) and outputs a single line showing:

Active model name
Context window fill percentage with a color-coded bar (green < 50%, yellow 50–80%, red > 80%)
Active agent name when an agent is running
Total cumulative session tokens

The source is maintained at scripts/statusline.ps1 in this platform repo.

Relationship to repo-level configuration¶

The user-level files provide the base layer. Each repo's .claude/ folder and root CLAUDE.md add project-specific context on top. Repo-level settings extend but do not replace user-level settings — agents from both scopes are available in a repo session, and the permission allow-lists from both settings.json files are merged.

See repo settings for the full repo-level standard.