Configuration

This document covers configuration options for Claude Session Tools.

Server Configuration

Port Settings

The server listens on port 3000 by default. To change:

Option 1: Environment variable

PORT=8080 npm start

Option 2: Modify server.ts

const PORT = process.env.PORT || 8080;

Vite Development Server

Configure the Vite development server in vite.config.ts:

export default defineConfig({
  server: {
    port: 5173,  // Development server port
    proxy: {
      '/api': 'http://localhost:3000',
      '/ws': {
        target: 'ws://localhost:3000',
        ws: true
      }
    }
  }
});

Status Detection Configuration

Stuck Threshold

The default stuck threshold is 15 seconds. To modify, edit StatusDetector.ts:

const STUCK_THRESHOLD_SECONDS = 30;  // Increase to 30 seconds

Custom Patterns

Add custom detection patterns in StatusDetector.ts:

private patterns = {
  idle: [
    /> .*\? for shortcuts/,
    // Add custom idle patterns
  ],
  active: {
    thinking: [/Thinking/, /∴/],
    using_tools: [/●\s+[A-Z]/],
    // Add custom active patterns
  },
  waiting: {
    permission: [/❯.*Yes.*No/, /\(y\/n\)/],
    question: [/Would you like/, /Which/],
    // Add custom waiting patterns
  }
};

Ambient Sound Configuration

Default Session Settings

Modify default settings in ambientSound.ts:

private getDefaultConfig(): SessionSoundConfig {
  return {
    waitEnabled: true,
    idleEnabled: false,
    waitThresholdSeconds: 30,
    idleThresholdSeconds: 90,
    volume: 0.5,
    preferMusic: true
  };
}

Global Settings

private globalConfig: GlobalSoundConfig = {
  masterEnabled: true,
  stopMode: 'any',  // 'any' or 'all'
  syncSessions: true
};

Audio Files

Place custom audio files in app/public/sounds/:

app/public/sounds/
├── ambient-idle.mp3
├── ambient-wait.mp3
└── README.md

Supported formats: MP3, WAV, OGG (browser-dependent)

Log Directory Configuration

The system locates session logs through loggable-session. The default log directory is:

~/.loggable-session/sessions/<session-name>/

To use a custom location, modify the log path resolution in server.ts.

UI Configuration

Mantine Theme

Customize the UI theme in App.tsx:

import { MantineProvider, createTheme } from '@mantine/core';

const theme = createTheme({
  primaryColor: 'blue',
  fontFamily: 'Inter, sans-serif',
  // Additional theme options
});

function App() {
  return (
    <MantineProvider theme={theme}>
      {/* ... */}
    </MantineProvider>
  );
}

Color Mode

The application respects system color preferences by default. Users can toggle between light and dark modes.

Environment Variables

Variable	Default	Description
PORT	3000	Server port
NODE_ENV	development	Environment mode

Build Configuration

Production Build

npm run build        # Build client
npm run build:server # Build server

Output directories:

• Client: dist/
• Server: dist-server/

TypeScript Configuration

Modify tsconfig.json for TypeScript settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Performance Tuning

File Watcher Settings

Optimize chokidar settings in LogWatcher.ts:

const watcherOptions = {
  usePolling: false,       // Use native events (recommended)
  stabilityThreshold: 200, // Debounce in milliseconds
  awaitWriteFinish: {
    stabilityThreshold: 100,
    pollInterval: 50
  }
};

WebSocket Settings

For many concurrent connections, consider:

const wss = new WebSocketServer({
  server,
  maxPayload: 1024 * 1024,  // 1MB max message size
  clientTracking: true
});

Deployment Considerations

Reverse Proxy

When deploying behind nginx or similar:

location / {
  proxy_pass http://localhost:3000;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_set_header Host $host;
}

Process Management

Use PM2 or similar for production:

pm2 start dist-server/server.js --name claude-session-tools

Security

For production deployments:

1. Run behind a reverse proxy with HTTPS
2. Implement authentication middleware
3. Restrict CORS origins
4. Use environment-specific configuration