Posted inAI

Configuring Claude Code: A Guide to the settings.json File

AI tutorial - IT technology blog
AI tutorial - IT technology blog

The Frustration of Default Settings

I spent my first hour with Claude Code manually hitting the ‘y’ key. I was working on a legacy Node.js project with over 2,000 files and a convoluted build pipeline. If you’ve used Anthropic’s CLI tool, you know the workflow: it can refactor functions, run tests, and fix bugs directly in your terminal. But the out-of-the-box experience is surprisingly high-friction.

Every time I asked Claude to run a simple ls or grep, it paused for permission. It defaulted to Claude 3.5 Sonnet—which costs $3.00 per million input tokens—even for trivial documentation tasks that Haiku could handle for $0.25. Manually typing --model claude-3-5-haiku or --yes for every single interaction quickly became a momentum killer.

Why Command Line Flags Fall Short

By default, Claude Code operates with a strict safety-first mindset. It assumes nothing about your environment. While passing flags to the claude command works for one-off fixes, it doesn’t scale for an eight-hour workday.

Relying solely on CLI flags creates three specific bottlenecks:

  • Inconsistency: It’s easy to forget a safety flag and accidentally let the AI overwrite a .env file.
  • Budget Leaks: Without hard limits, a recursive loop in a shell script can drain your API credits before you finish your coffee.
  • Context Gaps: The AI won’t remember that your project uses Tab indentation or specific Vitest patterns unless you tell it every time.

Environment Variables vs. settings.json

You have two main ways to customize the CLI. The first is adding environment variables to your .zshrc or .bashrc. This works fine for your API key, but it gets messy when you try to define complex behaviors or excluded directories.

The settings.json approach is much cleaner. It allows for structured configuration that you can track in a private repo or sync across machines. It turns Claude from a generic chat bot into a specialized tool that understands your specific tech stack. In my experience, moving these configurations into a dedicated file reduces setup time by about 15 minutes every time I switch projects.

Configuring the settings.json File

On macOS and Linux, Claude Code looks for its configuration at ~/.claude.json (or a similar path depending on your version). Here are the parameters that actually impact your daily speed.

1. Model Selection and Cost Control

You don’t always need the heavy lifting of Sonnet. For basic file renaming or generating boilerplate, Haiku is 12x cheaper and significantly faster. You can set a default model to keep your costs predictable.

{
  "model": "claude-3-5-haiku-20241022",
  "max_tokens_to_sample": 4000,
  "temperature": 0
}

I always set temperature to 0 for coding. This ensures the output is deterministic. You want the AI to follow logic, not get “creative” with your production syntax.

2. Streamlining Permissions

The constant stream of Y/N prompts is the biggest complaint among CLI users. You can automate this without giving the AI total control. The best strategy is to auto-approve read-only actions while keeping write commands manual.

{
  "auto_approve": {
    "read_files": true,
    "list_files": true,
    "run_commands": ["ls", "pwd", "git status", "npm test"]
  }
}

By whitelisting npm test, you allow the AI to iterate on bug fixes autonomously. It can run the suite, see the failure, and try again without waiting for you to click ‘Allow’ twenty times.

3. Custom Instructions (The System Prompt)

This is where you define your team’s “Definition of Done.” If you use functional programming or strict TypeScript, put those requirements here so the AI doesn’t suggest outdated patterns.

{
  "custom_instructions": "Use TypeScript arrow functions. Prefer early returns for readability. Use Vitest for all unit tests. Ignore the /legacy-backup folder."
}

Organizing Your Workflow

The most effective setups don’t just use one massive global file. I’ve found that a tiered approach works best for professional environments.

Global vs. Local Configs

Keep your UI preferences, like "theme": "dark", in your global home directory. However, use project-level overrides for language-specific rules. An AI needs to behave differently when it moves from a React frontend to a Go backend.

Protecting Your Context Window

Claude can get confused if it reads 50MB of minified JavaScript. Use the ignore_patterns array to hide node_modules, dist folders, and large lockfiles. This keeps the context window clean and ensures the AI focuses only on the source code that matters.

A Production-Ready Example

Here is a configuration I use for modern TypeScript projects. It prioritizes speed and prevents the AI from hallucinating in large directories.

{
  "model": "claude-3-5-sonnet-20241022",
  "max_history_limit": 20,
  "auto_approve": {
    "read_files": true,
    "list_files": true,
    "run_commands": [
      "npm test",
      "git diff",
      "ls -la"
    ]
  },
  "custom_instructions": "You are a Senior Engineer. Be concise. Use early returns. When fixing bugs, check for architectural flaws before applying a patch.",
  "ignore_patterns": [
    "**/node_modules/**",
    "**/dist/**",
    "package-lock.json"
  ]
}

Final Adjustments

Once this is set up, the tool feels completely different. You stop micromanaging and start delegating. You can run claude "Fix the auth bug" and walk away for a minute. The AI will read the files, run the existing tests, and present a finished diff. If it still makes mistakes, don’t just blame the model—refine your ignore_patterns. Often, the AI fails simply because it’s looking at too much irrelevant data.

Share:
Tags: