vibe-log-cli CLAUDE.md

Claude Code - vibe-log CLI Development Notes

Project Architecture Overview

vibelog-cli is a TypeScript-based CLI application designed to track and analyze developer productivity sessions from Claude Code. It's distributed as an NPX package for cross-platform compatibility.

Key Technologies

• TypeScript 5.3+ - Type-safe development
• Commander.js - CLI command parsing and routing
• Inquirer.js - Interactive terminal UI components
• Axios - HTTP client for API communication
• Better-SQLite3 - Fast SQLite database access for Cursor IDE integration
• Chalk - Terminal string styling
• Ora - Elegant terminal spinners
• Conf - Encrypted configuration storage
• EventSource Polyfill - SSE client for real-time auth
• Vitest - Modern testing framework
• tsup - Zero-config TypeScript bundler

Core Directory Structure

vibelog-cli/
├── bin/              # NPX entry point
├── dist/             # Compiled JavaScript output
├── src/
│   ├── commands/     # CLI command implementations
│   ├── lib/          # Core business logic
│   │   ├── api-client.ts        # Secure API communication
│   │   ├── auth/                # Authentication modules
│   │   ├── readers/             # Session data readers
│   │   ├── sub-agents/          # Claude Code sub-agent management
│   │   └── ui/                  # Terminal UI components
│   ├── types/        # TypeScript type definitions
│   └── utils/        # Helper utilities
└── tests/            # Comprehensive test suite

Main Components

Command Layer (/src/commands/)

Each command is a standalone module that handles specific CLI operations:

• init.ts - First-time setup and authentication flow
• send.ts - Upload session data to Vibelog API (supports silent mode for hooks)
  • IMPORTANT: Always use sendWithTimeout({ selectedSessions }) when uploading pre-selected sessions
  • Never call apiClient.uploadSessions() directly - the send command handles all session processing
  • The selectedSessions parameter expects SelectedSessionInfo[] from session-selector
• status.ts - Display user streak, points, and statistics (includes Cursor IDE stats)
• cursor-stats.ts - Display dedicated Cursor IDE statistics view
• auth.ts - Re-authentication for expired/invalid tokens
  • Supports wizardMode parameter to suppress menu-related messages during guided flows
• config.ts - Manage CLI configuration settings
• logout.ts - Clear stored authentication credentials
• install-hooks.ts - Legacy hook installation (redirects to hooks-manage)
• hooks-log.ts - View and manage hook execution logs
• hooks-manage.ts - Comprehensive hooks management interface
• verify-hooks.ts - Verify hook installation and configuration