CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-anthropic-ai--claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows

—

Pending
Overview
Eval results
Files

configuration.mddocs/

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):

  1. Command-line arguments
  2. Project-specific settings (.claude/settings.json)
  3. Project context file (CLAUDE.md)
  4. Global settings (~/.claude/settings.json)
  5. 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

Install with Tessl CLI

npx tessl i tessl/npm-anthropic-ai--claude-code

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