Claude Code Effort Level: Per-Project Configuration Guide with .claude/settings.json

Mar 13, 2026

I was tired of manually typing --effort high every time I worked on our legacy codebase. Then I discovered something that should have been obvious from the start - you can configure effort levels per project using .claude/settings.json.

The Problem

I work on multiple projects with different complexity levels:

A complex legacy codebase that needs maximum reasoning effort
Simpler greenfield projects that work fine with medium effort

Every time I switched projects, I had to remember to add the right CLI flags. Sometimes I forgot, and Claude would give me subpar responses on the complex code. Other times, I’d waste tokens by using maximum effort on trivial tasks.

I needed a way to set sensible defaults per repository.

The Solution: Per-Project Settings

Claude Code supports a configuration file at .claude/settings.json in your repository root. This file lets you set defaults that apply every time you work with that codebase.

Here’s what my legacy project’s settings look like:

{
  "effort": "high"
}

And my simpler project:

{
  "effort": "medium"
}

Now I don’t need to remember flags. When I work on the legacy codebase, Claude automatically uses high effort. When I switch to the simpler project, it uses medium.

How Settings Precedence Works

Claude Code applies settings in this order (highest priority first):

CLI flags - claude --effort high overrides everything
Project settings - .claude/settings.json in your repo root
Global settings - ~/.claude/settings.json for user-wide defaults

This means you can have a sensible global default, override it per-project, and still manually override with CLI flags when needed.

Combining with Model Selection

I also combine effort settings with model selection. For my complex project:

{
  "effort": "high",
  "model": "claude-sonnet-4-20250514"
}

This ensures I’m always using the right model with the right effort level for each codebase.

Why This Matters

Consistency: Every session with a repository uses the same settings. No more accidentally using low effort on complex tasks.

Efficiency: No need to specify flags manually every time you start Claude Code.

Team alignment: Commit the .claude/settings.json file, and your whole team gets consistent behavior.

Context-aware: Match the effort level to project complexity automatically.

The settings.json file supports many other configuration options beyond just effort and model. You can configure:

Tool permissions and auto-accept rules
Hook scripts for automation
MCP server configurations
Custom commands and aliases

The per-project approach is particularly powerful when combined with MCP servers - different projects can have access to different tools and data sources.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!