### Production Setup Environment Variables

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Example environment variables for a production setup. Configures load balancing, session duration, logging, log format, and offline pricing.

```bash
export LB_STRATEGY=session
export SESSION_DURATION_MS=7200000  # 2 hours
export LOG_LEVEL=INFO
export LOG_FORMAT=json
export CF_PRICING_OFFLINE=1  # Reduce external API calls
```

--------------------------------

### Development Setup Configuration

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Example JSON configuration for local development and debugging. Includes settings for port, logging, debug mode, and retries.

```json
{
  "lb_strategy": "session",
  "retry_attempts": 5,
  "retry_delay_ms": 2000,
  "retry_backoff": 2,
  "session_duration_ms": 3600000,
  "port": 3000
}
```

--------------------------------

### High Throughput Setup Environment Variables

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Example environment variables for a high throughput setup. Includes settings for load balancing strategy, retries, session duration, and logging level.

```bash
export LB_STRATEGY=session
export RETRY_ATTEMPTS=2
export RETRY_DELAY_MS=500
export SESSION_DURATION_MS=300000  # 5 minutes
export LOG_LEVEL=WARN  # Reduce logging overhead
```

--------------------------------

### ccflare Usage Examples

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

Demonstrates how to set environment variables for ccflare for different scenarios like development with debug logging, production with custom paths, and corporate proxy configurations. It shows how to export variables and start the application using 'bun start'.

```bash
# Development setup with debug logging
export ccflare_DEBUG=1
export LOG_LEVEL=DEBUG
export LOG_FORMAT=json
bun start

# Production setup with custom paths
export ccflare_CONFIG_PATH=/etc/ccflare/config.json
export ccflare_DB_PATH=/var/lib/ccflare/data.db
export PORT=3000
bun start

# Corporate proxy setup
export HTTP_PROXY=http://proxy.corp.com:8080
export HTTPS_PROXY=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1,internal.corp.com
bun start
```

--------------------------------

### Development Setup Environment Variables

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Example environment variables for a development setup. Configures port, logging level, log format, debug mode, and retry attempts.

```bash
export PORT=3000
export LOG_LEVEL=DEBUG
export LOG_FORMAT=pretty
export ccflare_DEBUG=1
export RETRY_ATTEMPTS=5
```

--------------------------------

### Install and Run ccflare

Source: https://github.com/snipeship/ccflare/blob/main/README.md

This snippet demonstrates how to clone the ccflare repository, install its dependencies using Bun, and start the application. It also shows how to configure the Claude SDK to use the local ccflare instance.

```bash
git clone https://github.com/snipeship/ccflare
cd ccflare
bun install

bun run ccflare

export ANTHROPIC_BASE_URL=http://localhost:8080
```

--------------------------------

### Clone and Run ccflare Locally

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Steps to clone the ccflare repository, install dependencies, build the project, and start the application for local development. Includes commands to run the TUI, server, or both, and how to add Claude accounts.

```bash
# Clone the repository
git clone https://github.com/snipeship/ccflare.git
cd ccflare

# Install dependencies
bun install

# Build the project (dashboard and TUI)
bun run build

# Start ccflare (TUI + Server combined)
bun run ccflare

# Or start components separately:
# Terminal UI only
bun run tui

# Server only (without TUI)
bun run server

# Server with hot-reload (development)
bun run dev:server

# In another terminal, add Claude accounts
bun run ccflare --add-account myaccount
```

--------------------------------

### Session Persistence Setup Environment Variables

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Example environment variables for session persistence. Configures load balancing strategy, session duration, retries, and logging level.

```bash
export LB_STRATEGY=session
export SESSION_DURATION_MS=21600000  # 6 hours
export RETRY_ATTEMPTS=3
export LOG_LEVEL=INFO
```

--------------------------------

### Install ccflare CLI

Source: https://github.com/snipeship/ccflare/blob/main/docs/cli.md

Steps to clone the ccflare repository, install dependencies using Bun, and build the CLI.

```bash
git clone https://github.com/snipe-code/ccflare.git
cd ccflare
bun install
bun run build
```

--------------------------------

### Install ccflare and Dependencies

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

This snippet shows how to clone the ccflare repository and install its dependencies using Bun.

```bash
git clone https://github.com/snipeship/ccflare.git
cd ccflare
bun install
```

--------------------------------

### High Throughput Setup Configuration

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Example JSON configuration optimized for maximum request throughput. Includes settings for load balancing strategy, retries, and port.

```json
{
  "lb_strategy": "session",
  "retry_attempts": 2,
  "retry_delay_ms": 500,
  "retry_backoff": 1.5,
  "session_duration_ms": 300000,
  "port": 8080
}
```

--------------------------------

### Production Setup Configuration

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Recommended JSON configuration for production deployments. Includes settings for load balancing, retries, session duration, port, and offline pricing.

```json
{
  "lb_strategy": "session",
  "retry_attempts": 3,
  "retry_delay_ms": 1000,
  "retry_backoff": 2,
  "session_duration_ms": 7200000,
  "port": 8080
}
```

--------------------------------

### Session Persistence Setup Configuration

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Example JSON configuration ideal for maintaining conversation context. Features settings for load balancing, retries, session duration, and port.

```json
{
  "lb_strategy": "session",
  "retry_attempts": 3,
  "retry_delay_ms": 1000,
  "retry_backoff": 2,
  "session_duration_ms": 21600000,
  "port": 8080
}
```

--------------------------------

### Starting ccflare TUI and Server

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Commands to start the ccflare application in different modes. This includes starting with the Terminal User Interface (TUI) and server, starting only the server, and viewing command-line help.

```bash
# Start ccflare in interactive mode (TUI + Server)
ccflare

# Or from source:
bun run ccflare

# Start server only (no TUI)
ccflare --serve

# View help for all available commands
ccflare --help
```

--------------------------------

### Running the ccflare Server

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Instructions for starting the ccflare production server using Bun. It includes commands for starting the server normally and with hot reload for development.

```bash
# Start the production server (port 8080)
bun run server
# or
bun run start
# or
bun run start

# Start the server with hot reload
bun run dev:server
```

--------------------------------

### Start ccflare Server and TUI

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

Demonstrates starting the ccflare server, optionally with the interactive Terminal UI (TUI). It also shows how to specify a custom session duration.

```bash
bun run ccflare
bun run server
SESSION_DURATION_MS=21600000 bun run server
```

--------------------------------

### PM2 Process Management Setup

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Instructions for installing PM2, a popular Node.js process manager, globally using npm. This is a prerequisite for managing ccflare as a service in production environments.

```bash
# Install PM2 globally
npm install -g pm2
```

--------------------------------

### Clone and Install ccflare

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Steps to clone the ccflare repository, add the upstream remote, and install project dependencies using Bun.

```bash
git clone https://github.com/YOUR_USERNAME/ccflare.git
cd ccflare
git remote add upstream https://github.com/ORIGINAL_OWNER/ccflare.git
bun install
```

--------------------------------

### Start ccflare Server

Source: https://github.com/snipeship/ccflare/blob/main/docs/cli.md

Command to start the ccflare API server with its dashboard interface.

```bash
ccflare --serve
```

--------------------------------

### Check for Running Ccflare Processes

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

These commands list all running processes associated with 'bun start' or 'ccflare --serve', useful for identifying and managing multiple Ccflare instances to prevent database lock errors.

```bash
ps aux | grep "bun start" | grep -v grep
```

```bash
ps aux | grep "ccflare --serve" | grep -v grep
```

--------------------------------

### Application Configuration Example

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

An example JSON configuration file (`~/.config/ccflare/config.json`) for ccflare application settings, including load balancing strategy, client ID, retry mechanisms, session duration, and port.

```json
// ~/.config/ccflare/config.json (or platform-specific location)
{
  "lb_strategy": "session",
  "client_id": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
  "retry_attempts": 3,
  "retry_delay_ms": 1000,
  "retry_backoff": 2,
  "session_duration_ms": 18000000,  // 5 hours
  "port": 8080
}
```

--------------------------------

### Automate ccflare Account Setup

Source: https://github.com/snipeship/ccflare/blob/main/docs/cli.md

Demonstrates how to add multiple accounts using a loop and monitor account status with the `watch` command.

```bash
# Add multiple accounts via script
for i in {1..3}; do
  ccflare --add-account "account-$i" --mode max --tier 5
done

# Monitor account status
watch -n 5 'ccflare --list'
```

--------------------------------

### Get Available Strategies API

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Lists all strategies that are currently supported and available for use. Note that only 'session' is currently supported due to potential issues with other strategies.

```http
GET /api/strategies
```

```json
["session"]
```

--------------------------------

### Agent File Format Example

Source: https://github.com/snipeship/ccflare/blob/main/docs/architecture.md

Provides an example of the agent file format, which includes frontmatter metadata (name, description, color, model) and the system prompt.

```markdown
---
name: "Agent Name"
description: "Agent description"
color: "blue"
model: "claude-opus-4-20250514"  # Optional, UI preference takes precedence
---

Your system prompt goes here...
```

--------------------------------

### Start and Manage ccflare with PM2

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Commands to start the ccflare application using a PM2 ecosystem file, save the current process list for future restarts, and generate a system startup script for PM2.

```bash
pm2 start ecosystem.config.js
pm2 save
pm2 startup
```

--------------------------------

### Bun Runtime Setup and TypeScript

Source: https://github.com/snipeship/ccflare/blob/main/docs/architecture.md

This snippet demonstrates the use of the Bun runtime for a project, highlighting its performance benefits and built-in TypeScript support. It serves as a foundational setup for modern JavaScript development.

```Shell
# Install Bun
curl -fsSL https://bun.sh/install | bash

# Initialize a new project with TypeScript support
bun init -y --template=react

# Run the development server
bun --hot src/index.ts
```

--------------------------------

### ccflare Manual Cleanup Response

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Example JSON response after a manual cleanup operation, detailing the number of removed requests and payloads, and the cutoff date.

```json
{ "removedRequests": 0, "removedPayloads": 123, "cutoffIso": "2025-08-20T12:34:56.000Z" }
```

--------------------------------

### React Dashboard UI with TanStack Query

Source: https://github.com/snipeship/ccflare/blob/main/docs/architecture.md

This example shows a basic React component setup for a dashboard, utilizing TanStack Query (@tanstack/react-query) for efficient data fetching and state management. It demonstrates fetching data and displaying it.

```JavaScript
import React from 'react';
import ReactDOM from 'react-dom/client';
import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query';

const queryClient = new QueryClient();

function ExampleComponent() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos');
      if (!response.ok) {
        throw new Error('Network response was not ok');
      }
      return response.json();
    },
  });

  if (isLoading) return 'Loading...';
  if (error) return 'An error has occurred: ' + error.message;

  return (
    <div>
      <h1>Todos</h1>
      <ul>
        {data.map(todo => (
          <li key={todo.id}>{todo.title}</li>
        ))}
      </ul>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <ExampleComponent />
    </QueryClientProvider>
  </React.StrictMode>
);

// Assume '/api/todos' endpoint returns JSON like: [{id: 1, title: 'Learn React'}]
```

--------------------------------

### Develop ccflare Dashboard

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

Starts the ccflare dashboard development environment, allowing for real-time updates and testing of the dashboard UI.

```bash
bun run dev:dashboard
```

--------------------------------

### Verify ccflare Installation

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Commands to verify the ccflare installation by running type checking, linting, and formatting.

```bash
bun run typecheck
bun run lint
bun run format
```

--------------------------------

### Start ccflare Server Alias

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

An alias command to start the ccflare server. It is functionally equivalent to `bun run server`.

```bash
bun run start
```

--------------------------------

### ccflare Configuration File Example

Source: https://github.com/snipeship/ccflare/blob/main/docs/api-http.md

An example JSON configuration file for ccflare, showing various settings such as load balancing strategy, client ID, retry parameters, port, and stream body capture size.

```json
{
  "lb_strategy": "session",
  "client_id": "your-oauth-client-id",
  "retry_attempts": 3,
  "retry_delay_ms": 1000,
  "retry_backoff": 2,
  "session_duration_ms": 18000000,
  "port": 8080,
  "stream_body_max_bytes": 262144
}
```

--------------------------------

### Future Test Structure Example

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

An example illustrating the planned co-location of test files with their corresponding source code within the project structure.

```bash
packages/core/
├── src/
│   ├── index.ts
│   ├── index.test.ts
│   ├── utils.ts
│   └── utils.test.ts
└── package.json
```

--------------------------------

### Troubleshoot TUI Won't Start

Source: https://github.com/snipeship/ccflare/blob/main/docs/tui.md

Provides troubleshooting steps for when the ccflare TUI fails to start. It includes checking for port conflicts, killing existing processes, and restarting with a different port.

```bash
# Check if port is in use
lsof -i :8080

# Kill existing process if needed
kill -9 <PID>

# Start with different port
bun run dev --port 8081
```

--------------------------------

### ccflare Configuration File Example

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

An example of a JSON configuration file for ccflare, which can override environment variables. This file allows for centralized configuration of various settings like load balancing strategy, client ID, retry parameters, session duration, and server port.

```json
{
  "lb_strategy": "session",
  "client_id": "your-client-id",
  "retry_attempts": 5,
  "retry_delay_ms": 2000,
  "retry_backoff": 1.5,
  "session_duration_ms": 7200000,
  "port": 3000
}
```

--------------------------------

### Get ccflare Help

Source: https://github.com/snipeship/ccflare/blob/main/docs/cli.md

Displays all available commands and options for the ccflare CLI, with both long and short help flags.

```bash
ccflare --help
ccflare -h
```

--------------------------------

### Start ccflare Server

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

Starts only the ccflare server component without the TUI. This is useful for running the backend services independently.

```bash
bun run server
```

--------------------------------

### Run ccflare Development Environment

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Commands to start the ccflare server, CLI, TUI, or dashboard in development mode.

```bash
bun run dev:server
bun run dev:cli
bun run dev
bun run dev:dashboard
```

--------------------------------

### Start ccflare TUI

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

Starts the ccflare Terminal User Interface (TUI), which includes building the dashboard first. This is the primary command for interactive use.

```bash
bun run ccflare
```

--------------------------------

### docs: Example Commit Message for Contributing Guidelines

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

An example of a 'docs' type commit message for the contributing scope, indicating the addition of a testing guidelines section.

```bash
docs(contributing): add testing guidelines section
```

--------------------------------

### Make Script Executable and Run

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

Commands to make the debug script executable and redirect its output to a report file.

```shell
chmod +x debug-info.sh
./debug-info.sh > debug-report.txt
```

--------------------------------

### Start ccflare TUI in Development Mode

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

Starts the ccflare TUI in development mode, enabling features like hot reloading for a faster development feedback loop.

```bash
bun run dev
```

--------------------------------

### ccflare Configuration File Example (JSON)

Source: https://github.com/snipeship/ccflare/blob/main/docs/load-balancing.md

Provides an example of the ccflare configuration file (`~/.ccflare/config.json`). This file allows for persistent configuration of load balancing strategy, session duration, server port, client ID, and retry settings.

```json
{
    "lb_strategy": "session",
    "session_duration_ms": 18000000,
    "port": 8080,
    "client_id": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
    "retry_attempts": 3,
    "retry_delay_ms": 1000,
    "retry_backoff": 2
}
```

--------------------------------

### Prometheus Metrics Integration Example

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Provides an example TypeScript code snippet demonstrating how to define Prometheus metrics for ccflare, including counters, histograms, and gauges for tracking requests, duration, and active/rate-limited accounts. This is a future enhancement.

```typescript
// Example: packages/http-api/src/metrics.ts
import { register, Counter, Histogram, Gauge } from 'prom-client';

export const metrics = {
  requestsTotal: new Counter({
    name: 'ccflare_requests_total',
    help: 'Total number of requests',
    labelNames: ['method', 'status', 'account']
  }),
  
  requestDuration: new Histogram({
    name: 'ccflare_request_duration_seconds',
    help: 'Request duration in seconds',
    labelNames: ['method', 'status'],
    buckets: [0.1, 0.5, 1, 2, 5, 10]
  }),
  
  activeAccounts: new Gauge({
    name: 'ccflare_active_accounts',
    help: 'Number of active accounts',
    labelNames: ['tier']
  }),
  
  rateLimitedAccounts: new Gauge({
    name: 'ccflare_rate_limited_accounts',
    help: 'Number of rate limited accounts'
  })
};
```

--------------------------------

### Get ccflare Retention Policy

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

This HTTP GET request retrieves the current retention policy settings for ccflare, including payload and request days.

```http
GET /api/config/retention
```

--------------------------------

### Check ccflare Status

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

Demonstrates how to use the ccflare CLI to list the status of accounts, which is useful for troubleshooting why some accounts might not be in use.

```bash
ccflare --list
```

--------------------------------

### Start ccflare on a Custom Port

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

This javascript command demonstrates how to start the ccflare application on a custom port (e.g., 3000) by setting the PORT environment variable. This is a solution for 'Address already in use' errors.

```javascript
PORT=3000 bun start
```

--------------------------------

### ccflare Retention Policy Response

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Example JSON response showing the retention policy for ccflare, indicating days for payload and request data.

```json
{ "payloadDays": 7, "requestDays": 365 }
```

--------------------------------

### Dockerfile for ccflare Deployment

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

A multi-stage Dockerfile for building and deploying ccflare. The builder stage uses Oven/Bun to install dependencies and compile the application. The runtime stage uses a slim Debian image, copies the compiled binaries and assets, sets up the user and directories, and configures environment variables, volumes, health checks, and the entrypoint.

```dockerfile
# Multi-stage build for optimal size
FROM oven/bun:1 AS builder

WORKDIR /app

# Copy package files
COPY package.json bun.lockb ./ 
COPY apps/ ./apps/
COPY packages/ ./packages/
COPY tsconfig.json ./

# Install dependencies and build
RUN bun install --frozen-lockfile
RUN bun run build
RUN cd apps/server && bun build src/server.ts --compile --outfile dist/ccflare-server
RUN cd apps/cli && bun build src/cli.ts --compile --outfile dist/ccflare-cli

# Runtime stage
FROM debian:bookworm-slim

# Install runtime dependencies
RUN apt-get update && apt-get install -y \
    ca-certificates 
    && rm -rf /var/lib/apt/lists/*

# Create user
RUN useradd -r -s /bin/false ccflare

# Copy binary and dashboard
COPY --from=builder /app/apps/tui/dist/ccflare /usr/local/bin/ccflare
COPY --from=builder /app/packages/dashboard-web/dist /opt/ccflare/dashboard

# Set permissions
RUN chmod +x /usr/local/bin/ccflare

# Create data directories
RUN mkdir -p /data /config && chown -R ccflare:ccflare /data /config

USER ccflare

# Environment
ENV PORT=8080
ENV ccflare_CONFIG_PATH=/config/ccflare.json

EXPOSE 8080

VOLUME ["/data", "/config"]

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD ["/usr/local/bin/ccflare-server", "health"] || exit 1

ENTRYPOINT ["/usr/local/bin/ccflare", "--serve"]
```

--------------------------------

### Enable JSON Log Format

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

Sets the LOG_FORMAT environment variable to 'json' and starts the Ccflare server, configuring the application to output logs in JSON format for easier parsing.

```bash
export LOG_FORMAT=json
bun start
```

--------------------------------

### Compile ccflare Binary

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Instructions for compiling ccflare into a single executable binary using Bun. This includes building the main binary with TUI, CLI, and server functionality, as well as an optional standalone server binary. It also covers copying the binary to a deployment location and setting execute permissions.

```bash
# Build all components (dashboard and TUI)
bun run build

# Build the main ccflare binary (includes TUI, CLI, and server)
cd apps/tui
bun build src/main.ts --compile --outfile dist/ccflare --target=bun

# Build standalone server binary (optional, server-only deployment)
cd ../server
bun build src/server.ts --compile --outfile dist/ccflare-server

# Copy binary to deployment location
cp apps/tui/dist/ccflare /opt/ccflare/
# Make it executable
chmod +x /opt/ccflare/ccflare
```

--------------------------------

### Test Analytics API Endpoint

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

This command sends a GET request to the Ccflare analytics API endpoint for the last hour, used to verify the availability and response of the analytics data.

```bash
curl "http://localhost:8080/api/analytics?range=1h"
```

--------------------------------

### Set Proxy Environment Variables

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

Configures HTTP and HTTPS proxy settings for the current session. This is typically done before starting an application that needs to route its traffic through a proxy server.

```bash
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
```

--------------------------------

### Get Current Configuration API

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Retrieves the current configuration settings of the ccflare service. The response uses camelCase for keys, which may differ from the snake_case used in configuration files.

```http
GET /api/config
```

```json
{
  "lb_strategy": "session",
  "port": 8080,
  "sessionDurationMs": 18000000
}
```

--------------------------------

### ccflare Deployment Structure

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Illustrates the typical file structure for a ccflare binary deployment, including the main executable, configuration directory, and data directory for the database and logs.

```bash
/opt/ccflare/
├── ccflare             # Main binary (TUI + CLI + Server)
├── config/
│   └── config.json     # Configuration (optional)
└── data/
    ├── ccflare.db      # SQLite database
    └── logs/           # Log files (if configured)

**Note**: The configuration and database are automatically created in platform-specific directories:
- **Linux/macOS**: `~/.config/ccflare/`
- **Windows**: `%LOCALAPPDATA%\ccflare\` or `%APPDATA%\ccflare\`
```

--------------------------------

### Enable Debug Mode via Environment Variable

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

Sets the ccflare_DEBUG and LOG_LEVEL environment variables to enable debug mode and then starts the Ccflare server. This is useful for detailed logging and troubleshooting.

```bash
export ccflare_DEBUG=1
export LOG_LEVEL=DEBUG
bun start
```

--------------------------------

### Get Current Strategy API

Source: https://github.com/snipeship/ccflare/blob/main/docs/configuration.md

Fetches the currently active load balancing strategy. This endpoint provides a simple way to check the active strategy without retrieving the full configuration.

```http
GET /api/config/strategy
```

```json
{
  "strategy": "session"
}
```

--------------------------------

### Get ccflare System Information

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

Provides bash commands to retrieve essential system information for reporting bugs or troubleshooting, including Bun version, Node.js version, and operating system type.

```bash
bun --version
node --version
echo $OSTYPE
```

--------------------------------

### Check ccflare Health Endpoint

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

Shows how to use `curl` to check the health status of the ccflare service and provides an example of the expected JSON response, including status, account information, and uptime.

```bash
curl http://localhost:8080/health
```

```json
{
  "status": "ok",
  "accounts": {
    "total": 3,
    "active": 2,
    "paused": 1
  },
  "uptime": 3600000
}
```

--------------------------------

### Terminate Ccflare Processes

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

These commands forcefully terminate any running processes associated with 'bun start' or 'ccflare --serve', useful for resolving database lock issues caused by zombie processes.

```bash
pkill -f "bun start"
```

```bash
pkill -f "ccflare --serve"
```

--------------------------------

### Show Help via CLI

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

Displays the help message for the ccflare CLI, listing all available commands and options.

```bash
bun run apps/tui/src/main.ts --help
```

--------------------------------

### Build ccflare Landing Page

Source: https://github.com/snipeship/ccflare/blob/main/apps/lander/README.md

Builds the ccflare landing page, copying the source files to the distribution directory. This is a necessary step before deploying the static site.

```bash
# Build the site (copies src to dist)
bun run build
```

--------------------------------

### Deploy ccflare Landing Page with Wrangler CLI

Source: https://github.com/snipeship/ccflare/blob/main/apps/lander/README.md

Installs the Wrangler CLI and deploys the built landing page to Cloudflare Pages. This command requires the project to be built locally first.

```bash
# Install Wrangler
bun add -g wrangler

# Deploy
cd apps/lander
bun run build
wrangler pages deploy dist --project-name=ccflare-landing
```

--------------------------------

### Preview ccflare Landing Page Locally

Source: https://github.com/snipeship/ccflare/blob/main/apps/lander/README.md

Builds and previews the ccflare landing page locally. This command is used for development and testing the static site before deployment.

```bash
# Preview the site locally
bun run preview
```

--------------------------------

### PostgreSQL Schema for ccflare Scaling

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Example PostgreSQL schema for the 'accounts' and 'requests' tables, designed for scaling ccflare beyond single-instance deployments. Includes table definitions, data types, constraints, and indexes for performance.

```sql
-- PostgreSQL schema (example for future implementation)
CREATE TABLE accounts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) UNIQUE NOT NULL,
    provider VARCHAR(50) NOT NULL,
    api_key TEXT,
    refresh_token TEXT,
    access_token TEXT,
    expires_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    last_used TIMESTAMPTZ,
    request_count INTEGER DEFAULT 0,
    total_requests INTEGER DEFAULT 0,
    account_tier INTEGER DEFAULT 1,
    rate_limited_until TIMESTAMPTZ,
    session_start TIMESTAMPTZ,
    session_request_count INTEGER DEFAULT 0,
    paused BOOLEAN DEFAULT FALSE,
    rate_limit_status VARCHAR(50),
    rate_limit_reset TIMESTAMPTZ,
    rate_limit_remaining INTEGER
);

CREATE TABLE requests (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    timestamp TIMESTAMPTZ DEFAULT NOW(),
    method VARCHAR(10),
    path TEXT,
    account_used UUID REFERENCES accounts(id),
    status_code INTEGER,
    success BOOLEAN,
    error_message TEXT,
    response_time_ms INTEGER,
    failover_attempts INTEGER DEFAULT 0,
    model VARCHAR(100),
    input_tokens INTEGER,
    output_tokens INTEGER,
    cache_read_input_tokens INTEGER,
    cache_creation_input_tokens INTEGER,
    cost_usd DECIMAL(10, 6)
);

-- Indexes for performance
CREATE INDEX idx_requests_timestamp ON requests(timestamp DESC);
CREATE INDEX idx_requests_account ON requests(account_used);
CREATE INDEX idx_accounts_active ON accounts(paused, expires_at);
CREATE INDEX idx_accounts_rate_limit ON accounts(rate_limited_until);
```

--------------------------------

### Launch ccflare TUI

Source: https://github.com/snipeship/ccflare/blob/main/docs/tui.md

Instructions on how to launch the ccflare Terminal User Interface (TUI) using the package.json script or direct execution with Bun.

```bash
# Using the package.json script (recommended)
bun run dev

# Direct execution
bun run apps/tui/src/main.ts
```

--------------------------------

### Start ccflare TUI Only

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

Starts only the ccflare Terminal User Interface (TUI). This command is an alternative to the main `ccflare` command if only the TUI is needed.

```bash
bun run tui
```

--------------------------------

### ccflare TUI Command Line Options

Source: https://github.com/snipeship/ccflare/blob/main/docs/tui.md

Demonstrates various command-line options for the ccflare TUI, including help, serving the API, viewing logs, statistics, managing accounts, maintenance tasks, and performance analysis.

```bash
# Show help
bun run dev --help
bun run dev -h

# Start server only (no TUI)
bun run dev --serve [--port 8080]

# View logs  
bun run dev --logs [N]  # Stream logs (optionally show last N lines first)

# View statistics (JSON output)
bun run dev --stats

# Account management
bun run dev --add-account <name> [--mode max|console] [--tier 1|5|20]
bun run dev --list
bun run dev --remove <name>
bun run dev --pause <name>
bun run dev --resume <name>

# Maintenance
bun run dev --reset-stats
bun run dev --clear-history

# Performance analysis
bun run dev --analyze
```

--------------------------------

### Build Dashboard for Cloudflare Pages (Bash)

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

This script details the build process for the dashboard-web package, intended for deployment on Cloudflare Pages. It includes installing dependencies and running the build command. The output directory is specified for Cloudflare Pages configuration.

```bash
# Build script for Cloudflare Pages
cd packages/dashboard-web
bun install
bun run build

# Output directory: packages/dashboard-web/dist
```

--------------------------------

### Start ccflare Server with Hot Reload

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

Starts the ccflare server with hot reloading enabled, automatically restarting the server when code changes are detected.

```bash
bun run dev:server
```

--------------------------------

### Update ccflare Dependencies

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Instructions for updating ccflare dependencies using bun, relevant when running from source.

```bash
# Quarterly: Update dependencies (if running from source)
cd /path/to/ccflare
bun update
```

--------------------------------

### TypeScript Import Conventions Example

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Demonstrates correct import practices in TypeScript, emphasizing the use of path aliases for cross-package dependencies and relative imports within the same package. It highlights the preferred order of imports.

```typescript
// Good
import { Database } from '@ccflare/database';
import { LoadBalancer } from '@ccflare/load-balancer';
import { formatDate } from './utils';
import type { Account } from '@ccflare/types';

// Bad
import { Database } from '../../../packages/database/src';
```

--------------------------------

### Run ccflare Proxy

Source: https://github.com/snipeship/ccflare/blob/main/apps/lander/README.md

Clones the ccflare repository, installs dependencies, and runs the proxy server. The proxy provides a full server on port 8080 with an interactive TUI, web dashboard, and real-time analytics.

```bash
# Clone and run - that's it!
git clone https://github.com/snipeship/ccflare
cd ccflare
bun install
bun run ccflare
```

--------------------------------

### ccflare Quick Troubleshooting Steps

Source: https://github.com/snipeship/ccflare/blob/main/docs/troubleshooting.md

A checklist of common troubleshooting steps for ccflare, covering service health, account status, error logs, rate limits, network connectivity, and database integrity.

```bash
# 1. Service Health
curl http://localhost:8080/health

# 2. Account Status
ccflare --list

# 3. Recent Errors
grep ERROR /tmp/ccflare-logs/app.log | tail -20

# 4. Rate Limits
grep "rate.?limit" /tmp/ccflare-logs/app.log | tail -10

# 5. Network Connectivity
curl -I https://api.anthropic.com/v1/messages

# 6. Database Health
sqlite3 ~/.config/ccflare/ccflare.db "PRAGMA integrity_check;"
```

--------------------------------

### feat: Example Commit Message for Load Balancer

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

An example of a 'feat' type commit message for the load-balancer scope, detailing an improvement to session persistence and referencing an issue.

```bash
feat(load-balancer): improve session persistence

Enhances the session-based strategy to better handle failover scenarios
while maintaining session affinity. This reduces rate limit occurrences
and improves overall reliability.

Closes #123
```

--------------------------------

### Write Unit Tests with Bun

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Demonstrates how to write unit tests for functions using the Bun test runner. It covers mocking dependencies and testing different scenarios for a `calculateAccountWeight` function.

```typescript
import { describe, it, expect, mock } from 'bun:test';
import { calculateAccountWeight } from './utils';

describe('calculateAccountWeight', () => {
  it('should return 1 for pro tier accounts', () => {
    const account = { tier: 1, name: 'pro-account' };
    expect(calculateAccountWeight(account)).toBe(1);
  });
  
  it('should return 5 for max 5x tier accounts', () => {
    const account = { tier: 5, name: 'max-5x-account' };
    expect(calculateAccountWeight(account)).toBe(5);
  });
});
```

--------------------------------

### Start Server Without TUI

Source: https://github.com/snipeship/ccflare/blob/main/docs/tui.md

Explains how to start the ccflare server without the interactive TUI, specifying a custom port. This is useful for running ccflare as a background service.

```bash
# Start server without TUI
bun run dev --serve --port 8081
```

--------------------------------

### Create Systemd Service for ccflare

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Defines a systemd service file for the ccflare load balancer. It specifies dependencies, user, working directory, execution command, restart policy, environment variables, security settings, and resource limits. It also includes commands to create the user, directories, reload systemd, enable, and start the service.

```bash
sudo cat > /etc/systemd/system/ccflare.service << 'EOF'
[Unit]
Description=ccflare Load Balancer
After=network.target

[Service]
Type=simple
User=ccflare
Group=ccflare
WorkingDirectory=/opt/ccflare
ExecStart=/opt/ccflare/ccflare --serve
Restart=always
RestartSec=5

# Environment
Environment="PORT=8080"
Environment="LB_STRATEGY=session"
Environment="LOG_LEVEL=INFO"
Environment="LOG_FORMAT=json"
Environment="CLIENT_ID=9d1c250a-e61b-44d9-88ed-5944d1962f5e"
Environment="SESSION_DURATION_MS=18000000"
Environment="RETRY_ATTEMPTS=3"
Environment="RETRY_DELAY_MS=1000"
Environment="RETRY_BACKOFF=2"

# Security
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/ccflare/data

# Resource limits
LimitNOFILE=65536
LimitNPROC=4096

[Install]
WantedBy=multi-user.target
EOF

# Create user and directories
sudo useradd -r -s /bin/false ccflare
sudo mkdir -p /opt/ccflare/{config,data/logs}
sudo chown -R ccflare:ccflare /opt/ccflare

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable ccflare
sudo systemctl start ccflare
```

--------------------------------

### refactor: Example Commit Message for Database Migration

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

An example of a 'refactor' type commit message for the database scope, explaining the extraction of migration logic and noting a breaking change.

```bash
refactor(database): extract migration logic to separate module

This improves testability and makes the migration system more modular.

BREAKING CHANGE: Database.migrate() method signature has changed
```

--------------------------------

### Add Account with Options via CLI

Source: https://github.com/snipeship/ccflare/blob/main/docs/index.md

Adds a new account to ccflare with specified mode and tier options using the CLI. This allows for customized account creation.

```bash
bun run apps/tui/src/main.ts --add-account <name> --mode <max|console> --tier <1|5|20>
```

--------------------------------

### fix: Example Commit Message for Proxy Token Refresh

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

An example of a 'fix' type commit message for the proxy scope, addressing a token refresh race condition and explaining the solution.

```bash
fix(proxy): handle token refresh race condition

Multiple concurrent requests were causing token refresh stampedes.
Added mutex to ensure only one refresh happens at a time.
```

--------------------------------

### System Performance Tuning - File Descriptors and TCP

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Provides bash commands to optimize system performance by increasing file descriptor limits for the 'ccflare' user and tuning TCP parameters in `/etc/sysctl.conf` for high throughput.

```bash
# Increase file descriptor limits
echo "ccflare soft nofile 65536" >> /etc/security/limits.conf
echo "ccflare hard nofile 65536" >> /etc/security/limits.conf

# TCP tuning for high throughput
cat >> /etc/sysctl.conf << EOF
# TCP tuning
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.tcp_fin_timeout = 15
net.ipv4.tcp_keepalive_time = 300
net.ipv4.tcp_keepalive_probes = 5
net.ipv4.tcp_keepalive_intvl = 15

# Buffer sizes
net.core.rmem_default = 262144
net.core.wmem_default = 262144
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
EOF

# Apply changes
sysctl -p
```

--------------------------------

### List Available Strategies

Source: https://github.com/snipeship/ccflare/blob/main/docs/api-http.md

Lists all supported load balancing strategies.

```bash
curl http://localhost:8080/api/strategies
```

--------------------------------

### Reset Session if Expired in Ccflare

Source: https://github.com/snipeship/ccflare/blob/main/docs/load-balancing.md

TypeScript method to reset an account's session if it has expired or if no session start time is recorded. It updates the session start time and resets the request count.

```typescript
private resetSessionIfExpired(account: Account): void {
    const now = Date.now();
    
    if (!account.session_start || 
        now - account.session_start >= this.sessionDurationMs) {
        // Reset session via StrategyStore
        this.store.resetAccountSession(account.id, now);
        account.session_start = now;
        account.session_request_count = 0;
    }
}
```

--------------------------------

### ccflare Dashboard Development

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Commands for building and running the ccflare dashboard in development mode using Bun.

```bash
# Build the dashboard
bun run build:dashboard

# Run dashboard in development mode
bun run dev:dashboard
```

--------------------------------

### Start CLAUDE Load Balancer

Source: https://github.com/snipeship/ccflare/blob/main/CLAUDE.md

Starts the CLAUDE load balancer proxy on port 8080. This server distributes requests across multiple OAuth accounts to prevent rate limiting.

```shell
bun start
```

--------------------------------

### ccflare Production Builds

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Commands for building all ccflare applications or specific applications (dashboard, TUI, lander) for production using Bun.

```bash
# Build all applications
bun run build

# Build specific applications
bun run build:dashboard
bun run build:tui
bun run build:lander
```

--------------------------------

### Document Public APIs with JSDoc

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Provides an example of using JSDoc comments to document a TypeScript function, including parameter descriptions, return types, and usage examples. This is crucial for maintaining code clarity and usability.

```typescript
/**
 * Selects the best account for handling a request based on the configured strategy.
 * 
 * @param accounts - List of available accounts
 * @param strategy - Load balancing strategy to use
 * @returns The selected account or null if no accounts are available
 * 
 * @example
 * const account = selectAccount(accounts, 'session');
 * if (account) {
 *   await forwardRequest(account, request);
 * }
 */
export function selectAccount(
  accounts: Account[], 
  strategy: LoadBalancingStrategy
): Account | null {
  // ...
}
```

--------------------------------

### TypeScript Naming Conventions Example

Source: https://github.com/snipeship/ccflare/blob/main/docs/contributing.md

Provides examples of recommended naming conventions in TypeScript, including camelCase for variables and functions, PascalCase for types and interfaces, and UPPER_SNAKE_CASE for constants. It also shows prefixing boolean variables.

```typescript
const MAX_RETRIES = 3;
const isRateLimited = true;

interface AccountStatus {
  hasValidToken: boolean;
  isActive: boolean;
}
```

--------------------------------

### Run ccflare Proxy

Source: https://github.com/snipeship/ccflare/blob/main/apps/lander/src/index.html

This snippet demonstrates the basic steps to clone the ccflare repository, install dependencies, and run the Claude API proxy. It sets up a full proxy server, an interactive TUI, a web dashboard, and real-time analytics.

```bash
git clone https://github.com/snipeship/ccflare
cd ccflare
bun install
bun run ccflare
```

--------------------------------

### Build and Run ccflare Docker Container

Source: https://github.com/snipeship/ccflare/blob/main/docs/deployment.md

Commands to build the ccflare Docker image locally and run it as a detached container. It also shows how to use Docker Compose to manage the deployment.

```bash
# Build the Docker image
docker build -t ccflare:latest .

# Run with Docker
docker run -d \
  --name ccflare \
  -p 8080:8080 \
  -v $(pwd)/data:/data \
  -v $(pwd)/config:/config \
  -e LB_STRATEGY=session \
  ccflare:latest

# Or use Docker Compose
docker-compose up -d
```