User environment — global Claude Code settings

One tool among several

This page documents the Claude Code user-level layer. Claude Code is the Tier A client in a multi-model estate — Codex, Gemini, Cursor, and VS Code Copilot are configured differently (each has its own user-level config: ~/.codex/config.toml, ~/.gemini/, IDE settings). For the cross-tool model — what is canonical, what is a per-tool shim, and how each client wires the MCP — see the agents standard. The mechanics below (~/.claude/, hooks, subagents) are genuinely Claude-specific and are not emulated by other tools.

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             ← user-level utility agents (available in every repo)
│   ├── 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

D:\git\platform\.claude\             ← orchestration + workstream agents (committed, portable)
├── agents/
│   ├── orchestration-pm.md          ← estate orchestration coordinator
│   ├── security-waf-caf.md          ← WAF + CAF hard gate (opus)
│   ├── terraform-validator.md
│   ├── bicep-validator.md
│   ├── arm-validator.md
│   ├── ansible-linter.md
│   ├── powershell-linter.md
│   ├── gemini-runner.md
│   ├── reviewer.md                  ← workstream pipeline agents
│   ├── security-reviewer.md
│   ├── documenter.md
│   ├── coder.md
│   ├── planner.md
│   ├── operator.md
│   ├── investigator.md
│   ├── test-writer.md
│   ├── router.md
│   └── personas/                    ← pluggable PM personas
│       ├── ACTIVE                   ← one-line pointer to active persona (default: jarvis)
│       ├── jarvis.md
│       ├── neutral.md
│       └── brain.md
├── commands/                        ← /dispatch /sweep /second-opinion /persona /build etc.
├── skills/                          ← workstream-build/review/refactor/test/document/investigate/operate
└── hooks/                           ← block-secrets, validate-path, log-tokens, format-on-write, etc.

---

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 autonomous/confirm defaults

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

Cross-tool equivalents

Codex reads the same developer identity from ~/.codex/AGENTS.md (+ ~/.codex/config.toml for options); Gemini via its configured contextFileName; Cursor and Copilot from their own user settings. Keep the identity content consistent across them — the agents standard describes how to avoid maintaining it in five places.

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
- Azure login: kris@hybridsolutions.cloud
- Platform Engineering repo: D:\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)

## 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 |
| orchestration-pm | sonnet | Estate orchestration coordinator — dispatches validators, tracks registry |
| security-waf-caf | opus | WAF 5-pillar + CAF naming gate — hard merge blocker |
| terraform-validator | haiku | Validates iac-terraform repos (fmt, validate, tfsec) |
| bicep-validator | haiku | Validates iac-bicep repos (bicep build, PSRule.Rules.Azure) |
| arm-validator | haiku | Validates iac-arm repos (ARM-TTK) |
| ansible-linter | haiku | Validates iac-ansible repos (yamllint, ansible-lint, syntax-check) |
| powershell-linter | sonnet | Validates iac-powershell repos (PSScriptAnalyzer, Pester, header check) |
| gemini-runner | sonnet | Bulk sweeps + second-opinion via Gemini REST API |
| reviewer | sonnet | Code correctness, security, perf review on diffs |
| security-reviewer | sonnet | Security audit: injection, secrets, auth/authz, PII |
| documenter | sonnet | Writes docs — READMEs, runbooks, ADRs |

---

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(//d/git/**)" — pre-approves reading all files under D:\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 the agent roster 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.