Hidden Settings That Change Everything

Most developers who use Claude Code daily have never opened ~/.claude/settings.json.

That is a mistake. The defaults in that file were calibrated for a smaller model with a smaller context window. With 1M tokens available, several of those defaults actively work against you.

The Control Plane: settings.json

Claude Code reads its configuration from ~/.claude/settings.json. This file controls behavior across all sessions: how long conversations are retained, which hooks run, which tools are available, and more.

The basic structure:

{
  "cleanupPeriodDays": 365,
  "env": {
    "CLAUDE_BASH_MAX_OUTPUT": "100000"
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "Stop": []
  }
}

You can also have project-level overrides in .claude/settings.json inside any repo. Project settings layer on top of user settings, with project taking precedence for any key that appears in both.

cleanupPeriodDays — The Most Overlooked Setting

Default: 30

Claude Code deletes conversation history older than this many days. Every session you resume with --resume, every /insights query, every time you ask Claude "what did we work on last month?" — all of that depends on this retention window.

With the default of 30 days, you lose access to everything older than a month. Set it to 365 and you have a full year of session history available.

{
  "cleanupPeriodDays": 365
}

This is the one confirmed settings.json field that should be in every developer's config. The cost is minimal (conversation logs are small text files). The benefit is a coding partner that actually remembers your project decisions, your refactors, your lessons learned.

Bash Output Truncation — The Silent Limiter

Default behavior: terminal output from Bash tool calls is truncated at approximately 30,000 characters.

This sounds generous until you run a large test suite. A Python project with 500 tests might produce 50,000+ characters of pytest output. Claude sees the first 30K and makes a judgment call about test status based on a truncated log.

The failure mode is subtle: Claude says "tests are passing" when the truncated output happened to show only passing tests, while the failures are in the portion that was cut off.

To increase bash output capture, set the environment variable:

{
  "env": {
    "CLAUDE_BASH_MAX_OUTPUT": "100000"
  }
}

Verify the exact variable name against your Claude Code version's documentation — the mechanism for controlling this may vary. The principle remains: if you run large test suites or commands with verbose output, the default capture limit is a liability.

File Read Token Limits — Partial Reads Without Warning

Default behavior: the Read tool is bounded by an internal token limit per file read, roughly equivalent to 25,000 tokens of content.

For most source files, this is not a problem. But configuration files, generated code, large data fixtures, and long test suites can exceed it. When they do, Claude reads what it can and proceeds.

The 1M context window changes the math here significantly. There is no longer a technical reason to limit file reads so conservatively — the context can hold the content. But the default limits predate the 1M window.

The practical mitigation: when working with large files, instruct Claude explicitly:

When reading files that might be large, first check line count with `wc -l`.
If the file is long, use offset and limit parameters to read it in sections.

Put this in your project's CLAUDE.md and Claude will follow it reliably.

The 2000-Line Read Hard Limit

This one is structural, not configurable — and it is the most dangerous limit in the entire system.

Claude's Read tool has a hardcoded maximum of 2000 lines per call. When you ask Claude to read a file, it reads the first 2000 lines. If the file is 3000 lines, Claude has no idea. It reads lines 1-2000 and proceeds as if it has the complete file.

No error. No warning. No [truncated] indicator. Just silence.

The implications:

• Claude refactors the middle of a 3000-line file, not knowing there are 1000 more lines
• Claude reviews a config file and misses critical sections at the bottom
• Claude analyzes test coverage and reports on only the first 2000 lines of the test suite

The fix is a two-layer approach:

Layer 1 — CLAUDE.md instruction:

## File Reading Rules

Never assume a file is fully read after a single Read call.
For any file that might exceed 2000 lines, first run `wc -l <filepath>`.
If the line count exceeds 2000, use the offset and limit parameters to read
the file in chunks (e.g., offset=0, limit=2000, then offset=2000, limit=2000, etc.).

Layer 2 — PreToolUse hook (covered in depth in Lesson 140):

A hook that intercepts every Read call, checks the file's line count, and exits with code 2 (blocking) if the file exceeds 2000 lines without offset/limit parameters. This turns a silent failure into an enforced behavior.

Auto-Compact Threshold — Timing Is Everything

Default behavior: Claude Code triggers auto-compaction when context fill reaches approximately 95%.

The problem: quality degrades well before the 95% threshold. Around 70% context fill, Claude's responses become less precise — it is managing a large working memory and the coherence of its reasoning starts to suffer. By the time auto-compact triggers at 95%, you have already spent several interactions at degraded quality.

The better approach: trigger compaction earlier, at 70-75% fill, before quality degradation sets in.

How to enforce this manually: when you notice Claude's responses getting less sharp or more circular, check /stats for context fill percentage. If you are above 70%, use /compact proactively rather than waiting for auto-compact.

The instruction pattern that helps:

## Context Management

If context fill exceeds 70%, proactively suggest using /compact before continuing.
Do not wait for auto-compact to trigger.

How 1M Context Changes the Math

With 200K tokens, these limits made engineering sense. Every token was precious. Truncating bash output, limiting file reads, and compacting early were all reasonable tradeoffs.

With 1M tokens:

• A 3000-line file is roughly 30K tokens — 3% of available context
• Full pytest output for a 500-test suite might be 40K tokens — 4%
• A year of conversation history for an active session might be 100K tokens — 10%

The token math no longer justifies conservative limits. The constraints are now legacy defaults, not architectural requirements.

This is why understanding these settings matters: most of them have not been updated to reflect what 1M context actually enables. You are running a 1M token model on 200K token defaults. Closing that gap is a legitimate performance optimization.

The Settings.json Baseline

Here is a reasonable starting configuration that incorporates the principles from this lesson:

{
  "cleanupPeriodDays": 365,
  "env": {
    "CLAUDE_BASH_MAX_OUTPUT": "100000"
  }
}

Then in your project CLAUDE.md, add the file reading and context management instructions described above.

The hooks layer (PreToolUse guard for Read calls, Stop hook for test enforcement) is covered in Lessons 139 and 140. Together, they form a complete operational foundation.

Lesson 181 Drill

1. Open ~/.claude/settings.json — if it does not exist, create it
2. Set cleanupPeriodDays to 365
3. Add the CLAUDE_BASH_MAX_OUTPUT environment variable
4. Add a file reading instruction block to your project's CLAUDE.md
5. Run wc -l on three files in your current project and identify any that exceed 2000 lines

If you find files over 2000 lines, you have found a place where Claude has silently been reading partial data. Fix the Read calls before proceeding with any analysis of those files.