Configuration Options

Relevant source files

The following files were used as context for generating this wiki page:

• skills/token-optimizer/references/optimization-checklist.md
• skills/token-optimizer/references/implementation-playbook.md
• skills/token-optimizer/SKILL.md
• skills/token-coach/SKILL.md
• skills/token-coach/references/coach-patterns.md
• skills/token-optimizer/references/agent-prompts.md

Configuration options within the Token Optimizer project encompass environment variables, system settings, and architectural patterns designed to minimize token consumption and maximize context window efficiency in Claude Code and Codex environments. These options allow users to tune how the model interacts with project files, tools, and subagents.

Effective configuration involves a multi-tiered approach: managing global and project-level settings files, implementing file exclusion rules, and optimizing the structure of core documentation like CLAUDE.md. These settings directly impact the irreducible floor of context overhead and the speed at which the context window fills during a session. Sources: skills/token-optimizer/references/optimization-checklist.md:377-385, skills/token-optimizer/references/implementation-playbook.md:154-156

Runtime and Environment Variables

The project utilizes specific environment variables to control internal logic, runtime detection, and advanced model behaviors.

Environment Variable Reference

The following environment variables are audited and tuned by the system to manage token-relevant behaviors.

Variable	Default	Description
TOKEN_OPTIMIZER_RUNTIME	claude	Explicitly sets the runtime (claude, codex, opencode, copilot).
CLAUDE_CODE_MAX_THINKING_TOKENS	10,000	Controls the maximum budget for extended thinking (chain-of-thought).
CLAUDE_CODE_MAX_OUTPUT_TOKENS	16,384	Sets the maximum tokens Claude can generate per response.
MAX_MCP_OUTPUT_TOKENS	25,000	Limits the tokens a single MCP tool call can return to context.
ENABLE_TOOL_SEARCH	auto	Verifies Tool Search activity for MCP tool definition deferral.
BASH_MAX_OUTPUT_LENGTH	system	Limits the amount of stdout/stderr captured from Bash tool calls.
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE	Not set	Auto-removed. Undocumented var that triggers early compaction.
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB	1 (Rec)	Strips credentials from subprocesses (v2.1.83+).

Sources: skills/token-optimizer/references/optimization-checklist.md:395-460, skills/token-optimizer/SKILL.md:10-25, skills/token-optimizer/references/agent-prompts.md:275-295

Runtime Detection Logic

The system automatically detects the environment to prevent applying Claude-specific optimizations to incompatible runtimes like GitHub Copilot or OpenCode.

Permission and Exclusion Rules

File exclusion is primarily handled through the permissions.deny key in settings.json. This replaces the deprecated .claudeignore mechanism.

Exclusion Best Practices

Rules should be scoped to prevent Claude from attempting to read sensitive or high-noise files, which saves tokens by preventing these files from entering the context.

• Project-level (.claude/settings.json): Preferred for repository-specific noise like node_modules or dist.
• Global (~/.claude/settings.json): Used for security-critical excludes like .env or secrets/**.

JSON Configuration Example:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Read(./node_modules/**)",
      "Read(./dist/**)"
    ]
  }
}

Sources: skills/token-optimizer/references/implementation-playbook.md:65-85, skills/token-optimizer/references/optimization-checklist.md:58-75

Architectural Optimization Patterns

Configuration is not limited to key-value pairs; it includes the architectural "configuration" of project files.

CLAUDE.md Tiered Structure

To optimize for Prompt Caching, CLAUDE.md must be structured with static content first and volatile content last. Caching requires a stable prefix of at least 1024 tokens.

Tier	Category	Contents	Loading Behavior
Tier 1	Static	Identity, critical rules, key paths, model routing	Always loaded (~300 lines)
Tier 2	On-Demand	Workflows, domain docs, tool configs	Loaded via skill/command
Tier 3	Explicit	Full guides, templates, standards	Loaded only via explicit file reference

Sources: skills/token-optimizer/references/implementation-playbook.md:10-20, skills/token-optimizer/references/optimization-checklist.md:30-45, skills/token-coach/references/coach-patterns.md:15-25

Model Routing Instructions

Configuring subagent model selection in CLAUDE.md is cited as the highest-ROI behavioral optimization.

Hook Configurations

Hooks allow for automated token management at specific points in the session lifecycle. These are configured in settings.json.

• PreCompact: Used to guide what Claude preserves during context compaction (e.g., active decisions and error states).
• PostToolUse: Triggers auto-formatters on file writes to save output tokens otherwise spent on style explanations.
• SessionEnd: Triggers measure.py collect to save session token data for trend analysis.
• Conditional Hooks (v2.1.85+): Support an if field (e.g., "if": "tool_uses") to skip execution when not needed.

Sources: skills/token-optimizer/references/implementation-playbook.md:105-120, skills/token-optimizer/references/agent-prompts.md:155-170

Conclusion

Configuration options in Token Optimizer are designed to provide a "lean" startup environment. By combining precise settings.json environment variables with tiered documentation structures and model routing instructions, users can recover 5-15% of their context window through configuration cleanup alone. Sources: skills/token-optimizer/SKILL.md:5-10, skills/token-optimizer/references/optimization-checklist.md:380-385