· hands on
Claude Code Settings That Scale With Your TypeScript Team
Learn the configuration scopes in Claude Code, their precedence order, and how to use each one to streamline your TypeScript development workflow.
Claude Code reads configuration from multiple scopes. Each scope has a different file, a different audience, and a different level of authority. If you don't know which one wins when they conflict, you'll spend time debugging settings that silently get overridden. This guide walks through all scopes, explains the precedence order, and shows practical examples for TypeScript projects.
Contents
- The Scopes
- Managed Scope
- CLI Flags
- Local Project Scope
- Project Scope
- User Scope
- A Practical Setup for TypeScript Projects
The Scopes
Every Claude Code session merges settings from multiple layers. From highest to lowest priority:
- Managed: organization-enforced policies that cannot be overridden
- CLI flags: temporary session overrides passed on the command line
- Local Project: personal overrides for a single project, gitignored
- Project: shared team settings, checked into Git
- User: your personal defaults across all projects
When the same setting appears at multiple layers, the higher-priority scope wins. User settings get overridden by project settings, which can get overridden by local project settings. CLI flags override all file-based settings, and managed policies override everything.
Managed Scope
The managed scope is deployed by an organization's IT or DevOps team. It lives outside your home directory and your project, at /Library/Application Support/ClaudeCode/managed-settings.json on macOS or /etc/claude-code/managed-settings.json on Linux. Managed settings cannot be overridden by any other scope. Individual developers never edit this file directly.
CLI Flags
CLI flags are temporary overrides that last for a single session. They take precedence over everything except managed settings. Examples include claude --permission-mode auto to enable auto mode or claude --model claude-sonnet-4-5 to switch models. CLI flags are not persisted anywhere.
Local Project Scope
The local project scope lives at .claude/settings.local.json in your repository. It is gitignored, so it never gets committed. This is your personal escape hatch for project-specific tweaks that only make sense on your machine. It is also good for running hooks like automatic formatting when your team settings don't already have that. Local project scope overrides both project and user scope. You can also add personal project instructions in CLAUDE.local.md at the repo root.
Project Scope
The project scope lives at .claude/settings.json in your repository root. It gets checked into git, so everyone on your team shares the same configuration. This is where you define team-wide permissions, hooks, and tool restrictions. Since project scope overrides user scope, a team-wide deny rule cannot be bypassed by a developer's personal allow rule.
Project-level instructions go in CLAUDE.md at your repo root. For larger projects, you can organize rules into .claude/rules/ as separate files that Claude Code loads on demand.
User Scope
The user scope lives at ~/.claude/settings.json. It applies to every project you open with Claude Code on your machine. This is the right place for personal preferences that you want everywhere, like your default permission rules or allowed tools. You can also place a CLAUDE.md file at ~/.claude/CLAUDE.md for instructions that apply globally.
A Practical Setup for TypeScript Projects
Here is a setup that works well for TypeScript teams using Claude Code:
| File | Scope | What to put here |
|---|---|---|
~/.claude/settings.json | User | MCP servers you use everywhere, like a TypeScript language server |
.claude/settings.json | Project | Framework-specific MCP servers, like a Playwright MCP for end-to-end testing |
.claude/settings.local.json | Local Project | MCP servers with individual credentials, like a Figma MCP connected to your personal account |
Instruction files follow the same scoping pattern:
| File | Scope | What to put here |
|---|---|---|
~/.claude/CLAUDE.md | User | Personal coding style preferences and naming conventions |
CLAUDE.md | Project | Shared coding conventions, e.g. arrow functions, explicit return types, vitest for testing |
CLAUDE.local.md | Local Project | Personal overrides for a specific repo, like your preferred commit message format |