# Chronova

> Chronova is an advanced developer productivity analytics platform that tracks coding activity through heartbeat monitoring, integrates with WakaTime, and provides comprehensive insights into coding patterns, time allocation, and productivity metrics.

Chronova is built with Next.js 16, React 19, and TypeScript, offering a web dashboard with real-time analytics, goal tracking, and team organization features. The platform supports multi-editor environments (VS Code, JetBrains, Vim/Neovim, Sublime Text) and provides AI-assisted coding insights through its MCP Server integration.

## Docs

- [Documentation](https://chronova.dev/docs): Everything you need to connect WakaTime-compatible tooling to Chronova
- [Quick Install Guide](https://chronova.dev/docs): Platform-specific installation instructions for Linux, macOS, and Windows
- [Post-Installation Setup](https://chronova.dev/docs): API key configuration and verification steps
- [Troubleshooting](https://chronova.dev/docs): Common issues and solutions
- [Migration Guide](https://chronova.dev/docs): Step-by-step WakaTime to Chronova migration
- [Editor Integrations](https://chronova.dev/docs): VS Code, JetBrains, Vim/Neovim, Sublime Text plugin setup
- [AI Integration (MCP)](https://chronova.dev/docs): Model Context Protocol server configuration
- [FAQ](https://chronova.dev/docs): Frequently asked questions about Chronova
- [API Reference](https://chronova.dev/api-reference): Complete API documentation with examples
- [Downloads](https://chronova.dev/downloads): Mobile apps, CLI, and MCP server downloads
- [Privacy Policy](https://chronova.dev/privacy): Privacy policy and data handling practices
- [Terms of Service](https://chronova.dev/terms): Terms of service and usage agreement
- [Imprint](https://chronova.dev/imprint): Legal imprint and contact information

## API

### Authentication
- [API Authentication Methods](https://chronova.dev/api-reference#auth): Bearer Token, Basic Auth, X-API-KEY Header, Query Parameter
- [Session Management](https://chronova.dev/api-reference#auth): Create, exchange, and manage authentication sessions
- [OAuth Integration](https://chronova.dev/api-reference#auth): Google and GitHub OAuth login endpoints

### User Management
- [GET /api/v1/users/current](https://chronova.dev/api-reference): Fetch authenticated user profile and subscription state
- [PATCH /api/v1/users/current](https://chronova.dev/api-reference): Update public profile, privacy toggles, or display preferences
- [GET /api/v1/users/current/data-summary](https://chronova.dev/api-reference): Get comprehensive data overview including heartbeats, analytics, and goals
- [POST /api/v1/users/current/export](https://chronova.dev/api-reference): Export user data in multiple formats (JSON, Markdown, XML, CSV, XLS)
- [DELETE /api/v1/users/current/delete](https://chronova.dev/api-reference): Permanently delete user account and all associated data
- [GET /api/v1/users/current/wakatime](https://chronova.dev/api-reference): Get WakaTime integration status and configuration
- [PATCH /api/v1/users/current/wakatime](https://chronova.dev/api-reference): Update WakaTime integration settings
- [DELETE /api/v1/users/current/wakatime](https://chronova.dev/api-reference): Disconnect WakaTime integration
- [POST /api/v1/users/current/rotate-api-key](https://chronova.dev/api-reference): Rotate the current API key and generate a new one
- [GET /api/v1/users/current/api-key-history](https://chronova.dev/api-reference): Get API key rotation history for audit purposes
- [GET /api/v1/users/current/org](https://chronova.dev/api-reference): Get user organization information and membership details

### Analytics & Heartbeats
- [GET /api/v1/users/current/stats/{range}](https://chronova.dev/api-reference): Retrieve time-tracking statistics for predefined ranges (today, yesterday, last_7_days, last_30_days, last_6_months, last_year)
- [GET /api/v1/users/current/all_time_since_today](https://chronova.dev/api-reference): Get all-time cumulative statistics
- [GET /api/v1/users/current/durations](https://chronova.dev/api-reference): Get detailed duration data for coding sessions
- [POST /api/v1/users/current/heartbeats](https://chronova.dev/api-reference): Submit one or many activity heartbeats
- [GET /api/v1/users/current/heartbeats](https://chronova.dev/api-reference): Retrieve heartbeats with pagination
- [POST /api/v1/users/current/heartbeats.bulk](https://chronova.dev/api-reference): Submit multiple heartbeats in a single request (max 1000)
- [GET /api/v1/users/current/heartbeats.bulk](https://chronova.dev/api-reference): Retrieve heartbeats in bulk
- [GET /api/v1/users/current/analytics/commit-correlation](https://chronova.dev/api-reference): Correlate commits with coding sessions
- [GET /api/v1/users/current/external_durations](https://chronova.dev/api-reference): Get external duration data from connected services
- [POST /api/v1/users/current/external_durations](https://chronova.dev/api-reference): Create external duration from connected services

### Summaries & Time Tracking
- [GET /api/v1/users/current/summaries](https://chronova.dev/api-reference): Get daily coding summaries with language, project, and editor breakdowns
- [GET /api/v1/users/current/streaks](https://chronova.dev/api-reference): Get current streak information
- [GET /api/v1/users/current/focus](https://chronova.dev/api-reference): Get focus metrics and deep work sessions
- [GET /api/v1/users/current/analytics/focus](https://chronova.dev/api-reference): Get detailed focus analytics
- [GET /api/v1/users/current/statusbar/today](https://chronova.dev/api-reference): Get today's statusbar summary for editor plugins

### Organizations & Teams
- [GET /api/v1/organizations](https://chronova.dev/api-reference): List organizations for current user
- [POST /api/v1/organizations](https://chronova.dev/api-reference): Create a new organization
- [GET /api/v1/organizations/{orgId}](https://chronova.dev/api-reference): Get organization details including name, description, and subscription status
- [PATCH /api/v1/organizations/{orgId}](https://chronova.dev/api-reference): Update organization name, description, or settings
- [DELETE /api/v1/organizations/{orgId}](https://chronova.dev/api-reference): Permanently delete an organization
- [GET /api/v1/organizations/{orgId}/public](https://chronova.dev/api-reference): Get public organization information
- [GET /api/v1/organizations/{orgId}/members](https://chronova.dev/api-reference): List organization members
- [POST /api/v1/organizations/{orgId}/members](https://chronova.dev/api-reference): Add a member to the organization
- [PATCH /api/v1/organizations/{orgId}/members/{memberId}](https://chronova.dev/api-reference): Update member role or permissions
- [DELETE /api/v1/organizations/{orgId}/members/{memberId}](https://chronova.dev/api-reference): Remove a member from the organization
- [GET /api/v1/organizations/{orgId}/invites](https://chronova.dev/api-reference): List organization invites
- [POST /api/v1/organizations/{orgId}/invites](https://chronova.dev/api-reference): Send an invitation to join the organization
- [GET /api/v1/organizations/{orgId}/billing](https://chronova.dev/api-reference): Get billing information
- [POST /api/v1/organizations/{orgId}/billing](https://chronova.dev/api-reference): Update billing information
- [GET /api/v1/organizations/{orgId}/analytics](https://chronova.dev/api-reference): Get organization analytics
- [GET /api/v1/users/current/orgs](https://chronova.dev/api-reference): List organizations the current user belongs to

### Goals & Personal Tracking
- [GET /api/v1/users/current/goals](https://chronova.dev/api-reference): List configured goals with progress metrics
- [POST /api/v1/users/current/goals](https://chronova.dev/api-reference): Create a new goal for language, project, or editor usage
- [DELETE /api/v1/users/current/goals](https://chronova.dev/api-reference): Soft-delete a goal by ID
- [GET /api/v1/users/current/goals/analytics](https://chronova.dev/api-reference): Access goal analytics including streaks and achievement ratios
- [GET /api/v1/users/current/goals/suggestions](https://chronova.dev/api-reference): Get personalized goal suggestions based on coding patterns

### GitHub Integration
- [GET /api/v1/users/current/github/repositories](https://chronova.dev/api-reference): List connected GitHub repositories with metadata
- [PUT /api/v1/users/current/github/repositories](https://chronova.dev/api-reference): Update GitHub repository settings
- [POST /api/v1/users/current/github/repositories/refresh](https://chronova.dev/api-reference): Refresh the list of connected GitHub repositories
- [GET /api/v1/users/current/github/auth](https://chronova.dev/api-reference): Start the OAuth flow to connect GitHub
- [DELETE /api/v1/users/current/github/auth](https://chronova.dev/api-reference): Disconnect GitHub integration
- [GET /api/v1/users/current/projects](https://chronova.dev/api-reference): List all tracked projects with metadata and coding statistics
- [GET /api/v1/users/current/projects/privacy](https://chronova.dev/api-reference): Get project privacy settings
- [PATCH /api/v1/users/current/projects/privacy](https://chronova.dev/api-reference): Update project privacy settings
- [GET /api/v1/users/current/projects/{project}/commits](https://chronova.dev/api-reference): Retrieve commits for a project with correlated coding time
- [POST /api/v1/users/current/sync/commits](https://chronova.dev/api-reference): Sync commits from connected repositories
- [POST /api/v1/users/current/coupons/validate](https://chronova.dev/api-reference): Validate a promotional coupon code

### WakaTime Integration
- [POST /api/v1/wakatime/sync](https://chronova.dev/api-reference): Start a WakaTime data sync job
- [POST /api/v1/wakatime/export](https://chronova.dev/api-reference): Export WakaTime data to Chronova format
- [GET /api/v1/wakatime/jobs/{jobId}](https://chronova.dev/api-reference): Get status and progress of a WakaTime sync/export job
- [DELETE /api/v1/wakatime/jobs/{jobId}](https://chronova.dev/api-reference): Cancel a running WakaTime sync/export job
- [GET /api/v1/wakatime/jobs/{jobId}/stream](https://chronova.dev/api-reference): Stream real-time progress updates for a WakaTime job
- [GET /api/v1/users/current/wakatime/jobs](https://chronova.dev/api-reference): List all WakaTime sync/export jobs

### WakaTime Compatibility Layer
- [GET /api/v1/compat/waka/users/current](https://chronova.dev/api-reference): Return user info using WakaTime field names
- [POST /api/v1/compat/waka/users/current/heartbeats](https://chronova.dev/api-reference): Accept heartbeat payloads in WakaTime JSON format
- [GET /api/v1/compat/waka/users/current/heartbeats](https://chronova.dev/api-reference): Get heartbeats in WakaTime format
- [GET /api/v1/compat/waka/users/current/stats/{range}](https://chronova.dev/api-reference): Stats endpoint mirroring the WakaTime API contract
- [GET /api/v1/compat/waka/users/current/summaries](https://chronova.dev/api-reference): Return summaries in WakaTime-compatible structure
- [GET /api/v1/compat/waka/users/current/projects](https://chronova.dev/api-reference): Return projects in WakaTime format

### Public & Community
- [GET /api/v1/leaders](https://chronova.dev/api-reference): Get leaderboard data
- [GET /api/v1/public/stats](https://chronova.dev/api-reference): Get public platform statistics
- [GET /api/v1/users/{user}](https://chronova.dev/api-reference): Get public user profile by username
- [GET /api/v1/users/{user}/stats/{range}](https://chronova.dev/api-reference): Get public user statistics
- [GET /api/v1/users/{user}/goals](https://chronova.dev/api-reference): Get public user goals

### Onboarding
- [GET /api/v1/onboarding](https://chronova.dev/api-reference): Get current onboarding state
- [POST /api/v1/onboarding](https://chronova.dev/api-reference): Start or update onboarding
- [GET /api/v1/onboarding/status](https://chronova.dev/api-reference): Get onboarding status
- [POST /api/v1/onboarding/step-complete](https://chronova.dev/api-reference): Mark an onboarding step as completed
- [POST /api/v1/onboarding/skip](https://chronova.dev/api-reference): Skip onboarding
- [POST /api/v1/onboarding/complete](https://chronova.dev/api-reference): Complete onboarding flow
- [GET /api/v1/onboarding/configuration](https://chronova.dev/api-reference): Get onboarding configuration and tour settings
- [POST /api/v1/onboarding/analytics](https://chronova.dev/api-reference): Track an onboarding analytics event

## Tools

### Chronova CLI
- **Installation**: `curl -fsSL https://raw.githubusercontent.com/nx-solutions-ug/chronova-cli/main/install.sh | bash` (Linux/macOS) or `irm https://raw.githubusercontent.com/nx-solutions-ug/chronova-cli/main/install.ps1 | iex` (Windows)
- **Configuration**: Create `~/.chronova.cfg` with API key and URL:
  ```ini
  [settings]
  api_key = your-api-key-here
  api_url = https://chronova.dev/api/v1
  ```
- **Commands**: `chronova-cli --version`, `chronova-cli --today`, `chronova-cli --sync`
- **Migration**: Automatic WakaTime migration with backup, symlinks, and API key extraction
- **Source**: [https://github.com/nx-solutions-ug/chronova-cli](https://github.com/nx-solutions-ug/chronova-cli)

### MCP Server (@chronova/mcp-server)
- **Installation**: `npx -y @chronova/mcp-server` or `npm install -g @chronova/mcp-server` then `chronova-mcp-server`
- **Configuration**: Set `CHRONOVA_API_KEY` environment variable or use `~/.chronova.cfg`/`~/.wakatime.cfg`
- **OpenCode Configuration**:
  ```json
  {
    "mcp": {
      "chronova": {
        "type": "local",
        "command": ["npx", "-y", "@chronova/mcp-server"],
        "enabled": true,
        "env": {
          "CHRONOVA_API_KEY": "your-api-key"
        }
      }
    }
  }
  ```
- **Claude Desktop Configuration**:
  ```json
  {
    "mcpServers": {
      "chronova": {
        "command": "npx",
        "args": ["-y", "@chronova/mcp-server"],
        "env": {
          "CHRONOVA_API_KEY": "your-api-key"
        }
      }
    }
  }
  ```
- **Available Tools**:
  - `get_developer_context`: Get your profile, subscription, GitHub status, and organization memberships
  - `get_productivity_summary`: Aggregated coding stats by time range (today, last 7 days, etc.)
  - `get_recent_activity`: Recent coding heartbeats with language, editor, and project filters
  - `get_ai_insights`: AI vs manual coding analytics with adoption timelines
- **Source**: [https://github.com/nx-solutions-ug/chronova-mcp](https://github.com/nx-solutions-ug/chronova-mcp)

### Editor Plugins
- **Visual Studio Code**: `ext install WakaTime.vscode-wakatime` - Open Extensions panel (Ctrl+Shift+X) and search for "WakaTime"
- **JetBrains IDEs**: Settings → Plugins → Marketplace → "WakaTime" - Works with IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, and Rider
- **Neovim/Vim**: `Plug 'wakatime/vim-wakatime'` - Add to your plugin manager (vim-plug example shown)
- **Sublime Text**: Package Control: Install Package → "WakaTime" - Restart Sublime after installation
- **All Plugins**: [https://wakatime.com/plugins](https://wakatime.com/plugins)

### Mobile Apps
- **Android App**: Native Chronova experience for phones and tablets
  - Download: [https://github.com/nx-solutions-ug/chronova-android/releases](https://github.com/nx-solutions-ug/chronova-android/releases)
  - Requirements: Android 8.0+, ARM64 & x86 support
- **iOS App**: SwiftUI client with live widgets and offline queueing (in development)
  - TestFlight access coming soon
- **PWA (Web App)**: Progressive Web App for all modern browsers
  - Install via browser's "Install" or "Add to Home Screen" feature
  - Cross-platform support with offline capabilities coming

## Optional

### Development & Contribution
- [Source Code](https://github.com/nx-solutions-ug/chronova): Main Chronova repository
- [CLI Source](https://github.com/nx-solutions-ug/chronova-cli): Chronova CLI source code
- [MCP Server Source](https://github.com/nx-solutions-ug/chronova-mcp): MCP server source code
- [Android App Source](https://github.com/nx-solutions-ug/chronova-android): Android app source code
- [Issue Tracker](https://github.com/nx-solutions-ug/chronova/issues): Report bugs and request features
- [Discussions](https://github.com/nx-solutions-ug/chronova/discussions): Community discussions and Q&A

### Support & Community
- [Support Email](mailto:support@nx-solutions.de): Direct support for integration issues
- [GitHub Issues](https://github.com/nx-solutions-ug/chronova/issues): Report bugs and technical issues
- [Twitter/X](https://twitter.com/chronovadev): Latest updates and announcements
- [LinkedIn](https://linkedin.com/company/nx-solutions): Company updates and job opportunities
- [GitHub Discussions](https://github.com/nx-solutions-ug/chronova/discussions): Community discussions and Q&A

### Legal & Compliance
- [Privacy Policy](https://chronova.dev/privacy): Detailed privacy policy and data handling practices
- [Terms of Service](https://chronova.dev/terms): Complete terms of service and usage agreement
- [Imprint](https://chronova.dev/imprint): Legal imprint and contact information
- [GDPR Compliance](https://chronova.dev/privacy#gdpr): General Data Protection Regulation compliance information
- [Data Export Guide](https://chronova.dev/docs#export): How to export your data for compliance purposes

### Technical Resources
- [Architecture Overview](https://github.com/nx-solutions-ug/chronova#core-architecture): Core architecture and design patterns
- [API Rate Limits](https://chronova.dev/api-reference#limits): Throughput limits and best practices
- [Authentication Guide](https://chronova.dev/api-reference#auth): Detailed authentication methods and examples
- [Heartbeat Detection Pipeline](https://github.com/nx-solutions-ug/chronova#heartbeat-detection-pipeline): How language, editor, and OS detection works
- [Caching Strategy](https://github.com/nx-solutions-ug/chronova#caching-strategy): Redis-based caching with circuit breaker pattern

### Integration Examples
- [cURL Examples](https://chronova.dev/api-reference): cURL commands for API endpoints
- [JavaScript Examples](https://chronova.dev/api-reference): JavaScript fetch examples

### Subscription & Billing
- [Subscription Plans](https://chronova.dev/subscription): Free, Pro (monthly/yearly/lifetime), and organization team plans
- [Billing FAQ](https://chronova.dev/docs#billing): Common billing questions and answers
- [Coupon Validation](https://chronova.dev/api-reference): How to validate promotional coupon codes via API
- [Organization Billing](https://chronova.dev/api-reference): Manage team and organization billing
- [Payment Methods](https://chronova.dev/settings/billing): Supported payment methods and Stripe integration