Home / Documentation

Documentation

Complete guide to using and configuring Claude Code Alias

🚀 Basic Usage

Launching Claude Code

Once installed, you can launch Claude Code from any terminal with the simple command:

cc

This automatically:

  • Loads your custom environment variables from ~/.env.cc
  • Validates the OTEL endpoint connection
  • Launches Claude Code with telemetry enabled

Passing Arguments

You can pass any arguments to Claude Code as you normally would:

# Show help
cc --help

# Open a specific project
cc /path/to/project

# Use specific model
cc --model claude-3-opus

# Combine multiple arguments
cc --model claude-3-opus /path/to/project

Environment Loading

When you run cc, the function:

  1. Reads each line from ~/.env.cc
  2. Skips comments (lines starting with #) and empty lines
  3. Validates environment variable format
  4. Exports valid variables to the current session
  5. Warns about invalid lines

⚙️ Configuration

Environment Variables

The ~/.env.cc file contains all configuration options. Edit it with your preferred text editor:

nano ~/.env.cc
# or
vim ~/.env.cc

Core Settings

CLAUDE_CODE_ENABLE_TELEMETRY

Enable or disable telemetry collection.

CLAUDE_CODE_ENABLE_TELEMETRY=1  # Enable (default)
CLAUDE_CODE_ENABLE_TELEMETRY=0  # Disable

OTEL_METRICS_EXPORTER / OTEL_LOGS_EXPORTER

Configure which exporters to use for metrics and logs.

OTEL_METRICS_EXPORTER=otlp  # Use OTLP exporter
OTEL_LOGS_EXPORTER=otlp     # Use OTLP exporter

# Other options: console, none

OTEL_EXPORTER_OTLP_ENDPOINT

Set the endpoint for your OpenTelemetry collector.

# Local collector (default)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Remote collector
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com:4317

OTEL_EXPORTER_OTLP_PROTOCOL

Specify the protocol for OTLP communication.

OTEL_EXPORTER_OTLP_PROTOCOL=grpc       # gRPC (default)
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf  # HTTP with protobuf

Performance Tuning

Export Intervals

Control how frequently telemetry data is exported:

# Metrics export interval (milliseconds)
OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 seconds
OTEL_METRIC_EXPORT_INTERVAL=60000  # 1 minute (default)

# Logs export interval (milliseconds)
OTEL_LOGS_EXPORT_INTERVAL=5000   # 5 seconds (default)
OTEL_LOGS_EXPORT_INTERVAL=1000   # 1 second (for debugging)

Authentication

OTEL_EXPORTER_OTLP_HEADERS

Add authentication headers if your collector requires them:

# Bearer token authentication
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token-here"

# API key authentication
OTEL_EXPORTER_OTLP_HEADERS="X-API-Key=your-api-key"

# Multiple headers (comma-separated)
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token,X-Custom=value"

Privacy Settings

OTEL_LOG_USER_PROMPTS

Control whether user prompts are included in telemetry:

OTEL_LOG_USER_PROMPTS=1  # Include prompts (default)
OTEL_LOG_USER_PROMPTS=0  # Exclude prompts for privacy

🔄 Connection Handling

Automatic Connection Testing

When OTEL is configured, the alias automatically tests connectivity:

Checking connection to OTEL collector at localhost:4317...

Connection Failure Options

If the OTEL collector is unreachable, you'll see:

⚠️  Warning: Could not connect to OTEL collector at localhost:4317
   The claude-code-otel listener does not appear to be running.
   
Would you like to (s)kip setting OTEL environment variables, (r)etry, or (c)ontinue anyway? [s/r/c]
  • Skip (s): Unsets all OTEL variables and launches Claude Code without telemetry
  • Retry (r): Exits so you can start the collector and try again
  • Continue (c): Proceeds with OTEL variables set despite connection failure

Non-Interactive Mode

When running in scripts or CI/CD pipelines:

echo "y" | ./create_cc_alias.sh  # Auto-confirm installation
cc < /dev/null                    # Run in non-interactive mode

In non-interactive mode, the script automatically continues with OTEL setup even if connection fails.

📊 Grafana Integration

Accessing Dashboards

Once your OTEL collector is running with Grafana:

  1. Open browser to http://localhost:3000
  2. Login with default credentials (admin/admin)
  3. Navigate to Dashboards → Claude Code

Available Metrics

The Claude Code dashboard displays:

  • Request rate and latency
  • Token usage and costs
  • Error rates and types
  • Model performance comparison
  • Usage patterns over time

Custom Dashboards

You can create custom Grafana dashboards using these metric namespaces:

claude_code_requests_total
claude_code_tokens_used
claude_code_latency_seconds
claude_code_errors_total

🔍 Advanced Usage

Multiple Configurations

Create different environment files for various use cases:

# Create alternative config
cp ~/.env.cc ~/.env.cc.production

# Temporarily use different config
cp ~/.env.cc.production ~/.env.cc && cc

# Script to switch configs
alias cc-prod="cp ~/.env.cc.production ~/.env.cc && cc"
alias cc-dev="cp ~/.env.cc.development ~/.env.cc && cc"

Debugging Telemetry

Enable console exporter for debugging:

# In ~/.env.cc
OTEL_METRICS_EXPORTER=console
OTEL_LOGS_EXPORTER=console

# Run Claude Code to see telemetry in terminal
cc

Custom OTEL Collectors

Point to different collectors for different environments:

# Development
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Staging
OTEL_EXPORTER_OTLP_ENDPOINT=https://staging-otel.example.com:4317

# Production
OTEL_EXPORTER_OTLP_ENDPOINT=https://prod-otel.example.com:4317
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer prod-token"
Installation Troubleshooting