CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claude Code RiskExec is a Node.js CLI tool for setting up Claude Code configurations and providing real-time analytics. The project uses modern JavaScript/Node.js development practices and includes a comprehensive analytics dashboard with modular architecture.

Development Commands

Package Management

```
npm install
```
- Install all dependencies
```
npm install --save <package>
```
- Install a production dependency
```
npm install --save-dev <package>
```
- Install a development dependency
```
npm update
```
- Update all dependencies
```
npm audit
```
- Check for security vulnerabilities
```
npm audit fix
```
- Fix security vulnerabilities

Application Commands

```
npm start
```
- Run the CLI tool
```
npm run analytics:start
```
- Start the analytics dashboard server
```
npm run analytics:test
```
- Run analytics-specific tests
```
node src/analytics.js
```
- Direct analytics server startup

Testing Commands

```
npm test
```
- Run all tests with Jest
```
npm run test:watch
```
- Run tests in watch mode
```
npm run test:coverage
```
- Run tests with coverage report
```
npm run test:unit
```
- Run unit tests only
```
npm run test:integration
```
- Run integration tests only
```
npm run test:e2e
```
- Run end-to-end tests
```
npm run test:analytics
```
- Run analytics module tests
```
npm run test:all
```
- Run comprehensive test suite

Code Quality Commands

```
npm run lint
```
- Run ESLint (if configured)
```
npm run format
```
- Format code (if configured)
```
node --check src/analytics.js
```
- Check syntax

Development Tools

```
npm run dev:link
```
- Link package for local development
```
npm run dev:unlink
```
- Unlink package
```
npm version patch|minor|major
```
- Bump version
```
npm publish
```
- Publish to npm registry

Analytics Dashboard

Quick Start

# Start the analytics dashboard
npm run analytics:start

# Open browser to http://localhost:3333
# The dashboard provides real-time monitoring of Claude Code sessions

Key Features

Real-time Session Monitoring - Live tracking of active Claude Code conversations
Conversation State Detection - "Claude working...", "User typing...", "Awaiting input..."
Performance Analytics - System health, memory usage, and performance metrics
WebSocket Integration - Real-time updates without polling
Export Capabilities - CSV/JSON export of conversation data
Browser Notifications - Desktop alerts for state changes

Architecture

The analytics dashboard follows a modular architecture with:

Backend Modules: StateCalculator, ProcessDetector, ConversationAnalyzer, FileWatcher, DataCache
Frontend Components: Dashboard, ConversationTable, Charts, Services
Real-time Communication: WebSocket server with notification management
Performance Monitoring: Comprehensive metrics and health monitoring
Testing Framework: Unit, integration, and performance tests

Technology Stack

Core Technologies

Node.js - Runtime environment (v14.0.0+)
Express.js - Web server framework
WebSocket - Real-time communication (ws library)
Chokidar - File system watching
Jest - Testing framework

Frontend Technologies

Vanilla JavaScript - No framework dependencies for maximum compatibility
Chart.js - Data visualization
WebSocket Client - Real-time updates
CSS3 - Modern styling with responsive design

Development Tools

fs-extra - Enhanced file system operations
chalk - Terminal string styling
boxen - Terminal boxes
commander - CLI argument parsing
inquirer - Interactive command line prompts

CLI Dependencies

commander - Command-line interface framework
inquirer - Interactive command line prompts
ora - Terminal spinners
boxen - Terminal boxes for notifications
open - Cross-platform file opener

Analytics Dependencies

express - Web server framework
ws - WebSocket library for real-time communication
chokidar - File system watcher
fs-extra - Enhanced file system operations
chalk - Terminal string styling

Testing Framework

Jest - JavaScript testing framework
jest-watch-typeahead - Interactive test watching
Comprehensive test coverage with unit, integration, and performance tests

Code Quality Tools

ESLint - JavaScript linting (if configured)
Prettier - Code formatting (if configured)
Node.js built-in - Syntax checking with
```
node --check
```

Project Structure Guidelines

File Organization

src/
├── index.js             # CLI entry point
├── analytics.js         # Analytics dashboard server
├── analytics/           # Analytics modules
│   ├── core/           # Core business logic
│   │   ├── StateCalculator.js
│   │   ├── ProcessDetector.js
│   │   ├── ConversationAnalyzer.js
│   │   └── FileWatcher.js
│   ├── data/           # Data management
│   │   └── DataCache.js
│   ├── notifications/   # Real-time communication
│   │   ├── WebSocketServer.js
│   │   └── NotificationManager.js
│   └── utils/          # Utilities
│       └── PerformanceMonitor.js
├── analytics-web/       # Frontend components
│   ├── index.html      # Main dashboard page
│   ├── components/     # UI components
│   ├── services/       # Frontend services
│   └── assets/         # Static assets
├── templates/           # Configuration templates
└── utils/              # CLI utilities
tests/
├── unit/               # Unit tests
├── integration/        # Integration tests
├── e2e/               # End-to-end tests
└── fixtures/          # Test data

Naming Conventions

Files/Modules: Use PascalCase for classes (
```
StateCalculator.js
```
), camelCase for utilities
Classes: Use PascalCase (
```
StateCalculator
```
)
Functions/Variables: Use camelCase (
```
getUserData
```
)
Constants: Use UPPER_SNAKE_CASE (
```
API_BASE_URL
```
)
Private methods: Prefix with underscore (
```
_privateMethod
```
)

Node.js Guidelines

Module Organization

Use CommonJS modules (
```
module.exports
```
,
```
require()
```
)
Organize related functionality into classes
Keep modules focused and single-purpose
Use dependency injection for testability
Document public APIs with JSDoc comments

Code Style

Use meaningful variable and function names
Keep functions focused and single-purpose
Use async/await for asynchronous operations
Handle errors appropriately with try/catch blocks
Use console logging with appropriate levels (chalk for styling)

Best Practices

Use
```
fs-extra
```
for enhanced file operations
Prefer
```
path.join()
```
for cross-platform path handling
Use async/await instead of callbacks where possible
Handle process signals for graceful shutdown
Use environment variables for configuration

Testing Standards

Test Structure

Organize tests to mirror source code structure
Use descriptive test names that explain the behavior
Follow AAA pattern (Arrange, Act, Assert)
Use Jest fixtures and mocks for test data
Group related tests in
```
describe
```
blocks

Test Categories

Unit Tests - Test individual modules and functions in isolation
Integration Tests - Test module interactions and complete workflows
Performance Tests - Test system performance and memory usage
E2E Tests - Test complete user scenarios end-to-end

Jest Configuration

// jest.config.js
module.exports = {
  testEnvironment: 'node',
  collectCoverageFrom: [
    'src/**/*.js',
    '!src/**/*.test.js'
  ],
  coverageThreshold: {
    global: {
      branches: 70,
      functions: 70,
      lines: 70,
      statements: 70
    }
  }
};

Coverage Goals

Aim for 70%+ overall test coverage (80%+ for core modules)
Write unit tests for business logic
Use integration tests for module interactions
Mock external dependencies and services
Test error conditions and edge cases

Test Examples

// Unit test example
describe('StateCalculator', () => {
  let stateCalculator;
  
  beforeEach(() => {
    stateCalculator = new StateCalculator();
  });
  
  it('should detect active state for recent messages', () => {
    const messages = [/* test data */];
    const lastModified = new Date();
    
    const state = stateCalculator.determineConversationState(messages, lastModified);
    
    expect(state).toBe('active');
  });
});

Dependency Management

Node.js Environment Setup

# Ensure Node.js 14+ is installed
node --version

# Install dependencies
npm install

# Install development dependencies
npm install --save-dev jest

# Link for local development
npm link

Package Management Best Practices

Use
```
package.json
```
for dependency management
Pin major versions to avoid breaking changes
Use
```
npm audit
```
to check for security vulnerabilities
Keep dependencies up to date with
```
npm update
```

Analytics Modular Architecture

Implementation Details

The analytics dashboard has been refactored into a modular architecture in 4 phases:

Phase 1: Backend Modularization

StateCalculator - Conversation state detection logic
ProcessDetector - Running process detection and correlation
ConversationAnalyzer - Message parsing and analysis
FileWatcher - Real-time file system monitoring
DataCache - Multi-level caching system

Phase 2: Frontend Modularization

Dashboard - Main component orchestration
ConversationTable - Interactive conversation display
Charts - Data visualization components
StateService - Reactive state management
DataService - API communication with caching
WebSocketService - Real-time communication

Phase 3: Real-time Communication

WebSocketServer - Server-side WebSocket management
NotificationManager - Event-driven notifications
Real-time Updates - Live conversation state changes
Fallback Mechanisms - Polling when WebSocket unavailable

Phase 4: Testing & Performance

Comprehensive Test Suite - Unit, integration, and performance tests
PerformanceMonitor - System health and metrics tracking
Memory Management - Automatic cleanup and optimization
Production Readiness - Performance monitoring and error tracking

Security Guidelines

Dependencies

Regularly update dependencies with
```
npm audit
```
and
```
npm update
```
Use
```
npm audit
```
to check for known vulnerabilities
Pin major versions in package.json to avoid breaking changes
Use environment variables for sensitive configuration

Code Security

Validate input data appropriately
Use environment variables for API keys and configuration
Implement proper error handling without exposing sensitive information
Sanitize file paths and user inputs
Use HTTPS for production deployments

Development Workflow

Before Starting

Check Node.js version compatibility (14.0.0+)
Run
```
npm install
```
to install dependencies
Check syntax with
```
node --check src/analytics.js
```
Run initial tests with
```
npm test
```

During Development

Use meaningful variable and function names
Run tests frequently to catch issues early:
```
npm run test:watch
```
For frontend changes, let user handle analytics server startup - don't run
```
npm run analytics:start
```
automatically
Use meaningful commit messages

Before Committing

Run full test suite:
```
npm test
```
Check syntax:
```
node --check src/analytics.js
```
Test analytics functionality:
```
npm run analytics:test
```
Ensure no console errors in browser (if testing frontend)
Run performance tests if available

Component System Architecture

Core Component Types

This CLI tool manages a comprehensive component system for Claude Code configurations:

🤖 Agents (600+ specialists)

AI specialists organized by domain expertise:

Development:

frontend-developer

fullstack-developer

devops-engineer

Security:

security-auditor

penetration-tester

compliance-specialist

Data/AI:
```
data-scientist
```
,
```
ml-engineer
```
,
```
nlp-engineer
```

Business:

product-strategist

business-analyst

legal-advisor

⚡ Commands (200+ automations)

Custom slash commands for development workflows:

Setup:

/setup-ci-cd-pipeline

/setup-testing

/migrate-to-typescript

Performance:

/optimize-bundle

/performance-audit

/add-caching

Testing:
```
/generate-tests
```
,
```
/setup-e2e
```
,
```
/test-coverage
```

Documentation:

/update-docs

/generate-api-docs

/create-guide

🔌 MCPs (Model Context Protocol Integrations)

External service connections:

Databases:

postgresql-integration

supabase

mysql-integration

Development:

github-integration

context7

filesystem-access

Browser:

playwright-mcp

browsermcp

browser-use-mcp-server

⚙️ Settings

Claude Code configuration files:

Performance:

performance-optimization

bash-timeouts

mcp-timeouts

Security:

read-only-mode

deny-sensitive-files

allow-git-operations

Statuslines:

context-monitor

git-branch-statusline

time-statusline

🪝 Hooks

Automation triggers for development workflows:

Git:

auto-git-add

smart-commit

pre-commit-validation

Notifications:

discord-notifications

slack-notifications

telegram-notifications

Performance:

performance-monitor

lint-on-save

test-runner

Spec Kit & BMAD Workflow (Phase 1)

The repository ships with a lightweight Spec Kit setup that pairs with BMAD role agents to run gated feature development inside Claude Code.

Directory Layout

```
specs/constitution.md
```
— Phase 1 quality rules and review checklist.
```
specs/<feature>/spec.md
```
— Functional specification authored during
```
/specify
```
.
```
specs/<feature>/plan.md
```
— Technical plan from
```
/plan
```
.
```
specs/<feature>/tasks.md
```
— Task breakdown from
```
/tasks
```
.

Slash Commands

```
/specify
```
— Invokes bmad-analyst (with PM support) to create or revise the specification.
```
/plan
```
— Invokes bmad-architect to translate the spec into a technical blueprint.
```
/tasks
```
— Invokes bmad-pm (with QA partnership) to build the actionable task list.
```
/implement
```
— Invokes bmad-developer (with QA validation) to execute approved tasks.

Each command accepts an optional

<feature-name>

argument (default

Feature-A

) and reads/writes the corresponding files under

specs/

while enforcing constitution rules.

Active BMAD Agents

bmad-analyst — Requirements expert producing traceable specs with explicit open questions.
bmad-pm — Delivery lead defining milestones, ownership, and acceptance coverage.
bmad-architect — Technical planner documenting architecture decisions and validation strategy.
bmad-developer — Implementation specialist executing tasks with test evidence.
bmad-qa — Quality analyst designing and documenting validation and sign-off.

Refer to

.claude/agents/bmad-team/

for full agent prompts and to

.claude/commands/

for command details. Follow the gated order (Specify → Plan → Tasks → Implement) and obtain approvals at each stage before progressing.

Component Installation System

CLI Installation Patterns

# Install specific components
npx claude-code-riskexec@latest --agent <name>
npx claude-code-riskexec@latest --command <name>
npx claude-code-riskexec@latest --mcp <name>
npx claude-code-riskexec@latest --setting <name>
npx claude-code-riskexec@latest --hook <name>

# Batch installation
npx claude-code-riskexec@latest --agent security-auditor --command security-audit --setting read-only-mode

# Interactive mode
npx claude-code-riskexec@latest

Special Component Features

Statusline System with Python Scripts

Statuslines can reference external Python scripts
Files are downloaded automatically to
```
.claude/scripts/
```
relative to project
Example:
```
statusline/context-monitor
```
installs both JSON config and Python script
Implementation in
```
src/index.js:installIndividualSetting()
```
:

if (settingName.includes('statusline/')) {
  const pythonFileName = settingName.split('/')[1] + '.py';
  const pythonUrl = githubUrl.replace('.json', '.py');
  additionalFiles['.claude/scripts/' + pythonFileName] = {
    content: pythonContent,
    executable: true
  };
}

Component Generation System

The

generate_components_json.py

script creates the component catalog:

Scans all component directories recursively
Excludes
```
.py
```
files from public listings (they remain as background dependencies)
Generates
```
docs/components.json
```
for the web interface at riskexec.com
Handles file content embedding and metadata extraction

Important Implementation Notes

Path Handling

Relative Paths: Always use relative paths like
```
.claude/scripts/
```
for project-local files
Cross-platform: Use
```
path.join()
```
for cross-platform compatibility
No Hardcoding: Never hardcode user home directories or absolute paths

Context Monitor Implementation

The statusline context monitor system demonstrates key architectural patterns:

Component Download: Automatic download of related files (Python scripts)
Relative Installation: Files installed relative to project, not globally
Background Dependencies: Python files excluded from public component listings
Dynamic Loading: Components loaded and executed dynamically by Claude Code

Error Handling Patterns

Use try/catch blocks for async operations
Log errors with appropriate context using chalk for styling
Provide helpful error messages to users
Handle missing files or directories gracefully
Implement fallback mechanisms for network operations

Component Development Guidelines

Adding New Components

Structure: Follow existing directory patterns in
```
cli-tool/components/
```
Naming: Use descriptive, hyphenated names (
```
security-auditor.md
```
)
Documentation: Include clear descriptions and usage examples
Testing: Add tests for complex logic components
Generation: Run
```
python generate_components_json.py
```
to update catalog

Modifying Existing Components

Backward Compatibility: Ensure changes don't break existing installations
Version Management: Consider version bumping for breaking changes
Testing: Test component installation with
```
--setting
```
,
```
--agent
```
, etc.
Documentation: Update component descriptions if functionality changes

Publishing Workflow

Version Management

# Bump version (automatically updates package.json)
npm version patch   # 1.20.2 -> 1.20.3
npm version minor   # 1.20.3 -> 1.21.0  
npm version major   # 1.21.0 -> 2.0.0

# Publish to npm
npm publish

Pre-publish Checklist

All tests passing (
```
npm test
```
)
Component catalog updated (
```
python generate_components_json.py
```
)
No hardcoded paths or sensitive information
Version bumped appropriately
Git commits include all relevant files

Component Security

Never include hardcoded credentials or API keys in components
Validate all user inputs in components
Use relative paths (
```
.claude/scripts/
```
) instead of absolute paths
Review components for potential security vulnerabilities before publishing

This codebase represents a comprehensive Claude Code component ecosystem with real-time analytics, modular architecture, and extensive automation capabilities. The system is designed for scalability, maintainability, and ease of use while providing powerful development workflow enhancements.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Development Commands

Package Management

```
npm install
```
- Install all dependencies
```
npm install --save <package>
```
- Install a production dependency
```
npm install --save-dev <package>
```
- Install a development dependency
```
npm update
```
- Update all dependencies
```
npm audit
```
- Check for security vulnerabilities
```
npm audit fix
```
- Fix security vulnerabilities

Application Commands

```
npm start
```
- Run the CLI tool
```
npm run analytics:start
```
- Start the analytics dashboard server
```
npm run analytics:test
```
- Run analytics-specific tests
```
node src/analytics.js
```
- Direct analytics server startup

Testing Commands

```
npm test
```
- Run all tests with Jest
```
npm run test:watch
```
- Run tests in watch mode
```
npm run test:coverage
```
- Run tests with coverage report
```
npm run test:unit
```
- Run unit tests only
```
npm run test:integration
```
- Run integration tests only
```
npm run test:e2e
```
- Run end-to-end tests
```
npm run test:analytics
```
- Run analytics module tests
```
npm run test:all
```
- Run comprehensive test suite

Code Quality Commands

```
npm run lint
```
- Run ESLint (if configured)
```
npm run format
```
- Format code (if configured)
```
node --check src/analytics.js
```
- Check syntax

Development Tools

```
npm run dev:link
```
- Link package for local development
```
npm run dev:unlink
```
- Unlink package
```
npm version patch|minor|major
```
- Bump version
```
npm publish
```
- Publish to npm registry

Analytics Dashboard

Quick Start

# Start the analytics dashboard
npm run analytics:start

# Open browser to http://localhost:3333
# The dashboard provides real-time monitoring of Claude Code sessions

Key Features

Real-time Session Monitoring - Live tracking of active Claude Code conversations
Conversation State Detection - "Claude working...", "User typing...", "Awaiting input..."
Performance Analytics - System health, memory usage, and performance metrics
WebSocket Integration - Real-time updates without polling
Export Capabilities - CSV/JSON export of conversation data
Browser Notifications - Desktop alerts for state changes

Architecture

The analytics dashboard follows a modular architecture with:

Backend Modules: StateCalculator, ProcessDetector, ConversationAnalyzer, FileWatcher, DataCache
Frontend Components: Dashboard, ConversationTable, Charts, Services
Real-time Communication: WebSocket server with notification management
Performance Monitoring: Comprehensive metrics and health monitoring
Testing Framework: Unit, integration, and performance tests

Technology Stack

Core Technologies

Node.js - Runtime environment (v14.0.0+)
Express.js - Web server framework
WebSocket - Real-time communication (ws library)
Chokidar - File system watching
Jest - Testing framework

Frontend Technologies

Vanilla JavaScript - No framework dependencies for maximum compatibility
Chart.js - Data visualization
WebSocket Client - Real-time updates
CSS3 - Modern styling with responsive design

Development Tools

fs-extra - Enhanced file system operations
chalk - Terminal string styling
boxen - Terminal boxes
commander - CLI argument parsing
inquirer - Interactive command line prompts

CLI Dependencies

commander - Command-line interface framework
inquirer - Interactive command line prompts
ora - Terminal spinners
boxen - Terminal boxes for notifications
open - Cross-platform file opener

Analytics Dependencies

express - Web server framework
ws - WebSocket library for real-time communication
chokidar - File system watcher
fs-extra - Enhanced file system operations
chalk - Terminal string styling

Testing Framework

Jest - JavaScript testing framework
jest-watch-typeahead - Interactive test watching
Comprehensive test coverage with unit, integration, and performance tests

Code Quality Tools

ESLint - JavaScript linting (if configured)
Prettier - Code formatting (if configured)
Node.js built-in - Syntax checking with
```
node --check
```

Project Structure Guidelines

File Organization

src/
├── index.js             # CLI entry point
├── analytics.js         # Analytics dashboard server
├── analytics/           # Analytics modules
│   ├── core/           # Core business logic
│   │   ├── StateCalculator.js
│   │   ├── ProcessDetector.js
│   │   ├── ConversationAnalyzer.js
│   │   └── FileWatcher.js
│   ├── data/           # Data management
│   │   └── DataCache.js
│   ├── notifications/   # Real-time communication
│   │   ├── WebSocketServer.js
│   │   └── NotificationManager.js
│   └── utils/          # Utilities
│       └── PerformanceMonitor.js
├── analytics-web/       # Frontend components
│   ├── index.html      # Main dashboard page
│   ├── components/     # UI components
│   ├── services/       # Frontend services
│   └── assets/         # Static assets
├── templates/           # Configuration templates
└── utils/              # CLI utilities
tests/
├── unit/               # Unit tests
├── integration/        # Integration tests
├── e2e/               # End-to-end tests
└── fixtures/          # Test data

Naming Conventions

Files/Modules: Use PascalCase for classes (
```
StateCalculator.js
```
), camelCase for utilities
Classes: Use PascalCase (
```
StateCalculator
```
)
Functions/Variables: Use camelCase (
```
getUserData
```
)
Constants: Use UPPER_SNAKE_CASE (
```
API_BASE_URL
```
)
Private methods: Prefix with underscore (
```
_privateMethod
```
)

Node.js Guidelines

Module Organization

Use CommonJS modules (
```
module.exports
```
,
```
require()
```
)
Organize related functionality into classes
Keep modules focused and single-purpose
Use dependency injection for testability
Document public APIs with JSDoc comments

Code Style

Use meaningful variable and function names
Keep functions focused and single-purpose
Use async/await for asynchronous operations
Handle errors appropriately with try/catch blocks
Use console logging with appropriate levels (chalk for styling)

Best Practices

Use
```
fs-extra
```
for enhanced file operations
Prefer
```
path.join()
```
for cross-platform path handling
Use async/await instead of callbacks where possible
Handle process signals for graceful shutdown
Use environment variables for configuration

Testing Standards

Test Structure

Organize tests to mirror source code structure
Use descriptive test names that explain the behavior
Follow AAA pattern (Arrange, Act, Assert)
Use Jest fixtures and mocks for test data
Group related tests in
```
describe
```
blocks

Test Categories

Unit Tests - Test individual modules and functions in isolation
Integration Tests - Test module interactions and complete workflows
Performance Tests - Test system performance and memory usage
E2E Tests - Test complete user scenarios end-to-end

Jest Configuration

// jest.config.js
module.exports = {
  testEnvironment: 'node',
  collectCoverageFrom: [
    'src/**/*.js',
    '!src/**/*.test.js'
  ],
  coverageThreshold: {
    global: {
      branches: 70,
      functions: 70,
      lines: 70,
      statements: 70
    }
  }
};

Coverage Goals

Aim for 70%+ overall test coverage (80%+ for core modules)
Write unit tests for business logic
Use integration tests for module interactions
Mock external dependencies and services
Test error conditions and edge cases

Test Examples

// Unit test example
describe('StateCalculator', () => {
  let stateCalculator;
  
  beforeEach(() => {
    stateCalculator = new StateCalculator();
  });
  
  it('should detect active state for recent messages', () => {
    const messages = [/* test data */];
    const lastModified = new Date();
    
    const state = stateCalculator.determineConversationState(messages, lastModified);
    
    expect(state).toBe('active');
  });
});

Dependency Management

Node.js Environment Setup

# Ensure Node.js 14+ is installed
node --version

# Install dependencies
npm install

# Install development dependencies
npm install --save-dev jest

# Link for local development
npm link

Package Management Best Practices

Use
```
package.json
```
for dependency management
Pin major versions to avoid breaking changes
Use
```
npm audit
```
to check for security vulnerabilities
Keep dependencies up to date with
```
npm update
```

Analytics Modular Architecture

Implementation Details

The analytics dashboard has been refactored into a modular architecture in 4 phases:

Phase 1: Backend Modularization

StateCalculator - Conversation state detection logic
ProcessDetector - Running process detection and correlation
ConversationAnalyzer - Message parsing and analysis
FileWatcher - Real-time file system monitoring
DataCache - Multi-level caching system

Phase 2: Frontend Modularization

Dashboard - Main component orchestration
ConversationTable - Interactive conversation display
Charts - Data visualization components
StateService - Reactive state management
DataService - API communication with caching
WebSocketService - Real-time communication

Phase 3: Real-time Communication

WebSocketServer - Server-side WebSocket management
NotificationManager - Event-driven notifications
Real-time Updates - Live conversation state changes
Fallback Mechanisms - Polling when WebSocket unavailable

Phase 4: Testing & Performance

Comprehensive Test Suite - Unit, integration, and performance tests
PerformanceMonitor - System health and metrics tracking
Memory Management - Automatic cleanup and optimization
Production Readiness - Performance monitoring and error tracking

Security Guidelines

Dependencies

Regularly update dependencies with
```
npm audit
```
and
```
npm update
```
Use
```
npm audit
```
to check for known vulnerabilities
Pin major versions in package.json to avoid breaking changes
Use environment variables for sensitive configuration

Code Security

Validate input data appropriately
Use environment variables for API keys and configuration
Implement proper error handling without exposing sensitive information
Sanitize file paths and user inputs
Use HTTPS for production deployments

Development Workflow

Before Starting

Check Node.js version compatibility (14.0.0+)
Run
```
npm install
```
to install dependencies
Check syntax with
```
node --check src/analytics.js
```
Run initial tests with
```
npm test
```

During Development

Use meaningful variable and function names
Run tests frequently to catch issues early:
```
npm run test:watch
```
For frontend changes, let user handle analytics server startup - don't run
```
npm run analytics:start
```
automatically
Use meaningful commit messages

Before Committing

Run full test suite:
```
npm test
```
Check syntax:
```
node --check src/analytics.js
```
Test analytics functionality:
```
npm run analytics:test
```
Ensure no console errors in browser (if testing frontend)
Run performance tests if available

Component System Architecture

Core Component Types

This CLI tool manages a comprehensive component system for Claude Code configurations:

🤖 Agents (600+ specialists)

AI specialists organized by domain expertise:

Development:

frontend-developer

fullstack-developer

devops-engineer

Security:

security-auditor

penetration-tester

compliance-specialist

Data/AI:
```
data-scientist
```
,
```
ml-engineer
```
,
```
nlp-engineer
```

Business:

product-strategist

business-analyst

legal-advisor

⚡ Commands (200+ automations)

Custom slash commands for development workflows:

Setup:

/setup-ci-cd-pipeline

/setup-testing

/migrate-to-typescript

Performance:

/optimize-bundle

/performance-audit

/add-caching

Testing:
```
/generate-tests
```
,
```
/setup-e2e
```
,
```
/test-coverage
```

Documentation:

/update-docs

/generate-api-docs

/create-guide

🔌 MCPs (Model Context Protocol Integrations)

External service connections:

Databases:

postgresql-integration

supabase

mysql-integration

Development:

github-integration

context7

filesystem-access

Browser:

playwright-mcp

browsermcp

browser-use-mcp-server

⚙️ Settings

Claude Code configuration files:

Performance:

performance-optimization

bash-timeouts

mcp-timeouts

Security:

read-only-mode

deny-sensitive-files

allow-git-operations

Statuslines:

context-monitor

git-branch-statusline

time-statusline

🪝 Hooks

Automation triggers for development workflows:

Git:

auto-git-add

smart-commit

pre-commit-validation

Notifications:

discord-notifications

slack-notifications

telegram-notifications

Performance:

performance-monitor

lint-on-save

test-runner

Spec Kit & BMAD Workflow (Phase 1)

The repository ships with a lightweight Spec Kit setup that pairs with BMAD role agents to run gated feature development inside Claude Code.

Directory Layout

```
specs/constitution.md
```
— Phase 1 quality rules and review checklist.
```
specs/<feature>/spec.md
```
— Functional specification authored during
```
/specify
```
.
```
specs/<feature>/plan.md
```
— Technical plan from
```
/plan
```
.
```
specs/<feature>/tasks.md
```
— Task breakdown from
```
/tasks
```
.

Slash Commands

```
/specify
```
— Invokes bmad-analyst (with PM support) to create or revise the specification.
```
/plan
```
— Invokes bmad-architect to translate the spec into a technical blueprint.
```
/tasks
```
— Invokes bmad-pm (with QA partnership) to build the actionable task list.
```
/implement
```
— Invokes bmad-developer (with QA validation) to execute approved tasks.

Each command accepts an optional

<feature-name>

argument (default

Feature-A

) and reads/writes the corresponding files under

specs/

while enforcing constitution rules.

Active BMAD Agents

bmad-analyst — Requirements expert producing traceable specs with explicit open questions.
bmad-pm — Delivery lead defining milestones, ownership, and acceptance coverage.
bmad-architect — Technical planner documenting architecture decisions and validation strategy.
bmad-developer — Implementation specialist executing tasks with test evidence.
bmad-qa — Quality analyst designing and documenting validation and sign-off.

Refer to

.claude/agents/bmad-team/

for full agent prompts and to

.claude/commands/

for command details. Follow the gated order (Specify → Plan → Tasks → Implement) and obtain approvals at each stage before progressing.

Component Installation System

CLI Installation Patterns

# Install specific components
npx claude-code-riskexec@latest --agent <name>
npx claude-code-riskexec@latest --command <name>
npx claude-code-riskexec@latest --mcp <name>
npx claude-code-riskexec@latest --setting <name>
npx claude-code-riskexec@latest --hook <name>

# Batch installation
npx claude-code-riskexec@latest --agent security-auditor --command security-audit --setting read-only-mode

# Interactive mode
npx claude-code-riskexec@latest

Special Component Features

Statusline System with Python Scripts

Statuslines can reference external Python scripts
Files are downloaded automatically to
```
.claude/scripts/
```
relative to project
Example:
```
statusline/context-monitor
```
installs both JSON config and Python script
Implementation in
```
src/index.js:installIndividualSetting()
```
:

if (settingName.includes('statusline/')) {
  const pythonFileName = settingName.split('/')[1] + '.py';
  const pythonUrl = githubUrl.replace('.json', '.py');
  additionalFiles['.claude/scripts/' + pythonFileName] = {
    content: pythonContent,
    executable: true
  };
}

Component Generation System

The

generate_components_json.py

script creates the component catalog:

Scans all component directories recursively
Excludes
```
.py
```
files from public listings (they remain as background dependencies)
Generates
```
docs/components.json
```
for the web interface at riskexec.com
Handles file content embedding and metadata extraction

Important Implementation Notes

Path Handling

Relative Paths: Always use relative paths like
```
.claude/scripts/
```
for project-local files
Cross-platform: Use
```
path.join()
```
for cross-platform compatibility
No Hardcoding: Never hardcode user home directories or absolute paths

Context Monitor Implementation

The statusline context monitor system demonstrates key architectural patterns:

Component Download: Automatic download of related files (Python scripts)
Relative Installation: Files installed relative to project, not globally
Background Dependencies: Python files excluded from public component listings
Dynamic Loading: Components loaded and executed dynamically by Claude Code

Error Handling Patterns

Use try/catch blocks for async operations
Log errors with appropriate context using chalk for styling
Provide helpful error messages to users
Handle missing files or directories gracefully
Implement fallback mechanisms for network operations

Component Development Guidelines

Adding New Components

Structure: Follow existing directory patterns in
```
cli-tool/components/
```
Naming: Use descriptive, hyphenated names (
```
security-auditor.md
```
)
Documentation: Include clear descriptions and usage examples
Testing: Add tests for complex logic components
Generation: Run
```
python generate_components_json.py
```
to update catalog

Modifying Existing Components

Backward Compatibility: Ensure changes don't break existing installations
Version Management: Consider version bumping for breaking changes
Testing: Test component installation with
```
--setting
```
,
```
--agent
```
, etc.
Documentation: Update component descriptions if functionality changes

Publishing Workflow

Version Management

# Bump version (automatically updates package.json)
npm version patch   # 1.20.2 -> 1.20.3
npm version minor   # 1.20.3 -> 1.21.0  
npm version major   # 1.21.0 -> 2.0.0

# Publish to npm
npm publish

Pre-publish Checklist

All tests passing (
```
npm test
```
)
Component catalog updated (
```
python generate_components_json.py
```
)
No hardcoded paths or sensitive information
Version bumped appropriately
Git commits include all relevant files

Component Security

Never include hardcoded credentials or API keys in components
Validate all user inputs in components
Use relative paths (
```
.claude/scripts/
```
) instead of absolute paths
Review components for potential security vulnerabilities before publishing

CLAUDE.md

Related Skills

Markdown Converter

Nano Banana Pro

1password