or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

authentication.md cli-interface.md cli-options.md configuration.md custom-commands.md hooks.md ide-integration.md index.md mcp-integration.md sdk-integration.md slash-commands.md

tile.json

Configuration System

Claude Code provides comprehensive configuration management through multiple configuration files, environment variables, and project-specific settings.

Capabilities

Configuration File Locations

Claude Code uses a hierarchical configuration system with multiple file locations.

# Global configuration directory
~/.claude/

# Project configuration
.claude/

# Main configuration files
~/.claude/settings.json         # Global settings (migrated from .claude.json)
.claude/settings.json          # Project-level settings
CLAUDE.md                      # Project-specific context and instructions
.mcp.json                      # MCP server configuration (project scope)

Configuration Priority (highest to lowest):

Command-line arguments
Project-specific settings (.claude/settings.json)
Project context file (CLAUDE.md)
Global settings (~/.claude/settings.json)
Default settings

Global Settings

Main configuration file for user-wide settings.

{
  "model": "claude-3-sonnet-20240229",
  "outputStyle": "explanatory",
  "permissions": {
    "allowedTools": [
      "Bash(git *)",
      "Read(*)",
      "Write(*.js)",
      "Write(*.ts)",
      "Write(*.json)"
    ],
    "blockedTools": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/bash-validator.py",
            "timeout": 5000
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Session started in $CLAUDE_PROJECT_DIR'"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/allowed/directory"]
    }
  },
  "cleanupPeriodDays": 30,
  "enableVimBindings": false,
  "statusLine": {
    "enabled": true,
    "format": "claude[%project%] %status%"
  }
}

Project Settings

Project-specific configuration that overrides global settings.

{
  "model": "claude-3-opus-20240229",
  "permissions": {
    "allowedTools": [
      "Bash(npm *)",
      "Bash(yarn *)",
      "Bash(git *)",
      "Read(*)",
      "Write(src/**/*)",
      "Write(tests/**/*)"
    ]
  },
  "customCommands": {
    "test-and-commit": {
      "command": "npm test && git add . && git commit",
      "description": "Run tests and commit if passing"
    }
  },
  "additionalDirectories": [
    "../shared-components",
    "../api-types"
  ]
}

Project Context File (CLAUDE.md)

Markdown file containing project-specific context and instructions.

# Project Context

## Project Overview
This is a React TypeScript application with Express.js backend.

## Architecture
- Frontend: React + TypeScript + Vite
- Backend: Express.js + TypeScript + PostgreSQL
- Testing: Jest + React Testing Library

## Development Guidelines
- Use functional components with hooks
- Prefer TypeScript strict mode
- All API responses must be typed
- Tests are required for new features

## Common Commands
- `npm run dev` - Start development server
- `npm run test` - Run test suite
- `npm run build` - Build for production
- `npm run typecheck` - Type checking

## Important Files
- `src/types/` - TypeScript type definitions
- `src/api/` - API client code
- `src/components/` - React components
- `tests/` - Test files

Environment Variables

Configure Claude Code behavior through environment variables.

# Configuration
export CLAUDE_CONFIG_DIR="/custom/config/path"
export ANTHROPIC_API_KEY="your-api-key"

# Model selection
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-3-sonnet-latest"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-3-opus-latest"

# IDE integration
export CLAUDE_CODE_AUTO_CONNECT_IDE="true"
export CLAUDE_CODE_SHELL_PREFIX="time"

# Debugging and logging
export ANTHROPIC_LOG="debug"
export DISABLE_INTERLEAVED_THINKING="false"

# Performance and timeouts
export BASH_DEFAULT_TIMEOUT_MS="120000"
export BASH_MAX_TIMEOUT_MS="600000"
export MCP_TIMEOUT="30000"
export MCP_TOOL_TIMEOUT="10000"

# Network configuration
export NO_PROXY="localhost,127.0.0.1"
export AWS_BEARER_TOKEN_BEDROCK="your-bedrock-token"

# Advanced options
export CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR="true"
export USE_BUILTIN_RIPGREP="true"

Key Environment Variables:

CLAUDE_CONFIG_DIR: Override configuration directory (supports XDG_CONFIG_HOME)
ANTHROPIC_API_KEY: Direct API key authentication
ANTHROPIC_DEFAULT_SONNET_MODEL: Control Sonnet model alias
ANTHROPIC_DEFAULT_OPUS_MODEL: Control Opus model alias
CLAUDE_CODE_AUTO_CONNECT_IDE: Enable/disable IDE auto-connection
CLAUDE_CODE_SHELL_PREFIX: Wrap shell commands with prefix
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR: Freeze working directory
USE_BUILTIN_RIPGREP: Control built-in ripgrep usage
NO_PROXY: Proxy bypass configuration
AWS_BEARER_TOKEN_BEDROCK: Bedrock API authentication
DISABLE_INTERLEAVED_THINKING: Disable thinking mode
ANTHROPIC_LOG: Debug logging level (debug, info, warn, error)
BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS: Bash command timeouts
MCP_TIMEOUT / MCP_TOOL_TIMEOUT: MCP server and tool timeouts

Hook Configuration

Detailed hook system configuration for custom behaviors.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "git status",
            "timeout": 5000
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Session ended at $(date)' >> ~/.claude/session.log"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/bash-security-check.py",
            "timeout": 3000
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/file-backup.sh",
            "timeout": 2000
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'User prompt: $CLAUDE_USER_PROMPT' >> ~/.claude/prompts.log"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/backup-conversation.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Task completed successfully' | notify-send 'Claude Code'"
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Subagent task completed'"
          }
        ]
      }
    ]
  }
}

Hook Types:

SessionStart: Executed when a new session begins
SessionEnd: Executed when session terminates
PreToolUse: Executed before any tool usage
UserPromptSubmit: Executed when user submits input
PreCompact: Executed before conversation compaction
Stop: Executed when main task completes
SubagentStop: Executed when subagent task completes

MCP Server Configuration

Configure Model Context Protocol servers for extended capabilities.

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed-directory"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "git": {
      "command": "mcp-server-git",
      "args": [
        "--repository",
        ".",
        "--branch",
        "main"
      ]
    },
    "database": {
      "command": "python3",
      "args": [
        "/path/to/mcp-database-server.py",
        "--connection-string",
        "postgresql://localhost/mydb"
      ],
      "env": {
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    },
    "web-search": {
      "command": "node",
      "args": [
        "/path/to/web-search-server.js"
      ],
      "env": {
        "SEARCH_API_KEY": "${SEARCH_API_KEY}"
      }
    }
  }
}

MCP Server Features:

Multiple server support
Environment variable injection
Server health monitoring
OAuth authentication support
Resource linking and annotations
Tool discovery and usage

Permission Configuration

Fine-grained control over tool permissions and security.

{
  "permissions": {
    "allowedTools": [
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(git status *)",
      "Bash(npm install *)",
      "Bash(npm run *)",
      "Read(*)",
      "Write(src/**/*.ts)",
      "Write(src/**/*.tsx)",
      "Write(tests/**/*)",
      "Write(docs/**/*.md)"
    ],
    "blockedTools": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)",
      "Write(/etc/*)",
      "Write(/usr/*)",
      "Write(/bin/*)"
    ],
    "requireConfirmation": [
      "Bash(git reset --hard *)",
      "Bash(git push --force *)",
      "Write(package.json)",
      "Write(tsconfig.json)"
    ]
  }
}

Permission Patterns:

Tool(pattern): Allow tool with specific pattern
Tool(*): Allow tool with any arguments
*: Wildcard matching for any tool
Glob patterns for file paths
Regular expressions for complex matching

Output Style Configuration

Customize how Claude presents information and responses.

{
  "outputStyle": "explanatory",
  "customOutputStyles": {
    "learning": {
      "description": "Educational style with detailed explanations",
      "systemPrompt": "Explain concepts thoroughly with examples and context."
    },
    "concise": {
      "description": "Brief, direct responses",
      "systemPrompt": "Be concise and direct. Minimize explanations."
    },
    "expert": {
      "description": "Advanced technical responses",
      "systemPrompt": "Assume expert-level knowledge. Use technical terminology."
    }
  }
}

Built-in Output Styles:

explanatory: Default style with explanations
learning: Educational style for learning
concise: Brief, direct responses
Custom styles can be defined

Configuration Management Commands

Manage configuration through CLI commands.

# Edit global configuration
claude /config --edit

# Validate configuration
claude /doctor

# Reset to defaults
claude /config --reset

# Backup configuration
claude /config --backup

# Show current configuration
claude /config --show

# Import configuration
claude /config --import config-backup.json

# Export configuration
claude /config --export my-config.json

Configuration Migration

Handle upgrades and configuration migration.

{
  "version": "2.0",
  "migrationNotes": {
    "1.x-to-2.x": "Settings moved from .claude.json to ~/.claude/settings.json"
  }
}

Migration Features:

Automatic configuration migration
Backup creation during upgrades
Version compatibility checking
Migration notifications and guidance

Configuration Validation

Validate configuration files for correctness.

# Validate all configuration
claude /doctor

# Validate specific config file
claude --validate-config ~/.claude/settings.json

# Check hook scripts
claude /doctor --check-hooks

# Verify MCP servers
claude /doctor --check-mcp

Validation Checks:

JSON syntax validation
Schema compliance
Hook script execution
MCP server connectivity
Permission rule validity
File path accessibility